Make a template dynamic

You can include variables and functions that are evaluated and resolved when a template is run. Rather than manually updating the same value across a template, such as changing the number of instances on a service or editing configuration values in a secret group, you can provide these values dynamically using references, arguments, and functions.

This means you can create one template as the source of truth for your infrastructure, and deploy the same projects in different regions or cloud providers, or using different configuration values and secrets.

Node references allow you to access the outputs from previous nodes in the workflow. You can use these, for example, to specify a build to deploy, a subdomain path to assign to a port, or a database or deployment status to check in a condition.

You can use arguments to provide configuration values to the template or your resources, argument overrides to supply secrets such as API tokens, and functions to manipulate data and provide different values based on arguments or node outputs.

You can include dynamic values in release flow and preview environment templates within a pipeline node that will resolve on a template run, and specify dynamic values that will persist into the created pipeline templates that will then resolve when the release flow or preview environment template is run.

Northflank will dry-run a template before any template nodes are executed to ensure any references, arguments, and functions in the template can be resolved.

Use dynamic values in the visual editor

You can include dynamic values in node forms by entering them in text fields as you would any other value. For example ${args.PROJECT_NAME} can be directly inserted into the Project name field of a project node.

Where node forms have non-text fields you can switch to references mode to enter a variable or function.

When you add a node to your template and save it, it will be given a reference property (ref) generated from the resource name.

You can use this reference to refer to the output of that node later in the template. This is useful if you have steps in your workflow that require confirmation that previous steps have been completed successfully, or need values from resources created earlier. When you add a node to your template you will be given the option, where relevant, to select resources from your template, allowing you to specify resources that have not yet been created.

For example, a start build node will include references to any build services in your template when you select the resource to start a build in, as well as any that are in the project context if the project currently exists in your team.

You can see the available properties for a reference by expanding output variables on the relevant node.

References to a node return a promise, which resolves to the relevant response from the node. References are accessed as code using the refs object, in the format ${refs.<reference-name>.<property>}.

"steps": [
  {
    "kind": "BuildService",
    "ref": "builder"
    "spec": {
      "name": "My build service",
      ...
    }
  },
  {
    "kind": "Build",
    "spec": {
      "id": "${refs.builder.id}",
      "type": "service",
      "branch": "main",
      "reuseExistingBuilds": true,
    },
    "condition": "success"
  },
]

Northflank DNS references

You can obtain the public DNS for a service from a reference in the following format: ${refs.<service-name>.ports.<array-number>.dns}. Ports are an array of objects, you must provide the array position of the port you want to get the DNS for. For example if the first port on your service is a public HTTP port, you would obtain the DNS with the following: ${refs.<service-name>.ports.0.dns}.

If you are using references to obtain the Northflank-generated DNS for a service, or connection details for an addon, you should include a condition node to make sure the service or addon is running. This will ensure the service or addon has obtained a subdomain before using the reference to obtain the DNS or connection details.

Dynamic domains

You can dynamically create subdomains in templates by configuring your domain to use wildcard redirect routing and certificate generation when you add it to Northflank.

You can then use the values from references and arguments to assign subdomains to your services, for example "${args.<argument-name>}.example.com" or "${refs.<reference-name>.<property>}.example.com".

You can also accept requests to any subdomain of the parent domain using wildcard subdomains.

Arguments can be used to store template configuration values, dynamic values that you want to change, or build and environment variables for services and secret groups. This allows you to change one value passed to your template, rather than potentially multiple values throughout your template code.

You can include arguments in your template, referenced in the format ${args.<argument-name>}, replacing <argument-name> with your key.

They are also useful if you have a value which is used repeatedly throughout the template that you want to change on subsequent template runs, or a value you wish to dynamically generate using a function.

Arguments are stored in the argument object at the top-level of the template as key-value pairs. If you enable GitOps the arguments object will be saved in your template file. Similarly, sharing a template will also share the arguments object.

It can be useful to include the keys for sensitive data in your arguments object for reference, but you should use placeholder values and not include the actual secrets. Secrets should only be provided to a template securely using argument overrides.

Argument overrides can be used to inject secure values into your template, or override existing argument values. Argument overrides are stored securely on Northflank, separately from your template. If you are using GitOps these will not be saved in your repository if you add the argument overrides in the Northflank UI using the template form. You should not commit argument overrides in your template.

You can configure argument overrides for a template on its settings page, which will override arguments with the same key in the arguments object. If the key specified in the overrides object does not exist in the arguments object, it will be inserted.

You can supply argument overrides using the API by including an argumentOverrides object containing the key-value pairs of arguments to override.

Run on creation overrides

If you are creating a template using the API you can also specify runOnCreationArgumentOverrides in options, which will only be used when the template is created if runOnCreation is set to true.

{
  "name": "Example template arguments",
  "description": "This is a sample template.",
  "apiVersion": "v1",
  "arguments": {
    "ARGUMENT_1": "default_1",
    "ARGUMENT_2": "default_2",
    "ARGUMENT_3": ""
  },
  "argumentOverrides": {
    "ARGUMENT_1": "hello",
    "ARGUMENT_2": "world",
    "ARGUMENT_3": ""
  },
  "options": {
    "runOnCreation": true,
    "runOnCreationArgumentOverrides": {
      "ARGUMENT_1": "goodnight",
      "ARGUMENT_2": "moon",
      "ARGUMENT_3": ""
    },
    "autorun": false
  },
  "spec": {
    "kind": "Workflow",
    "spec": {
      "type": "sequential",
      "steps": [
        ...
      ]
    }
  }
}

You can include functions in your template. Functions are called in the format: "${fn.<function-name>(<arguments>)}", for example "${fn.randomSecret(32, 'hex')}".

Functions are deterministic and will be evaluated on every template run, excluding the randomSecret function.

Functions can include references and arguments that do not resolve to a value, unlike the top-level of a template where references and arguments must resolve. Unresolved references and arguments will be treated as false if used as boolean arguments.

Functions are listed below, consisting of the function name, arguments and their types, and the purpose of the function.

General

String manipulation

Boolean functions

Boolean arguments can be provided as truthy and falsy values similar to JavaScript. They can accept booleans, strings, and numbers, and if a reference or argument does not resolve, it will be regarded as false.

Maths

{
  "apiVersion": "v1",
  "spec": {
    "kind": "Workflow",
    "spec": {
      "type": "sequential",
      "steps": [
        {
          "kind": "BuildService",
          "ref": "builder",
          "spec": {
            "name": "${args.repository}-builder",
            "billing": {
              "deploymentPlan": "nf-compute-50"
            },
            "vcsData": {
              "projectUrl": "https://github.com/${args.account}/${args.repository}",
              "projectType": "github"
            },
            "buildSettings": {
              "dockerfile": {
                "buildEngine": "kaniko",
                "dockerFilePath": "/Dockerfile",
                "dockerWorkDir": "/"
              }
            },
            "buildConfiguration": {
              "prRestrictions": [
                "*"
              ],
              "branchRestrictions": [
                "main"
              ]
            }
          }
        },
        {
          "kind": "Build",
          "ref": "build",
          "spec": {
            "id": "${refs.builder.id}",
            "type": "service",
            "branch": "${args.branch}"
          }
        },
        {
          "kind": "Condition",
          "spec": {
            "kind": "Build",
            "spec": {
              "type": "success",
              "data": {
                "buildId": "${refs.build.id}"
              }
            }
          }
        },
        {
          "kind": "DeploymentService",
          "spec": {
            "name": "${args.branch}-deployment",
            "billing": {
              "deploymentPlan": "${fn.if(fn.eq(args.branch, 'main'), 'nf-compute-100', 'nf-compute-50')}"
            },
            "deployment": {
              "instances": "${fn.if(fn.eq(args.branch, 'main'), 3, 1)}",
              "docker": {
                "configType": "default"
              },
              "storage": {
                "ephemeralStorage": {
                  "storageSize": 1024
                }
              },
              "internal": {
                "id": "${refs.builder.id}",
                "branch": "${args.branch}",
                "buildId": "${refs.build.id}"
              }
            },
            "runtimeEnvironment": {
              "ENVIRONMENT": "${fn.if(fn.eq(args.branch, 'main'), 'production', 'development')}"
            }
          }
        }
      ]
    }
  }
}

You can execute nodes on a conditional basis, so that they can either be skipped or executed depending on your requirements. You can use this to include nodes or entire workflows in your template that you don't want to execute on every template run, for example a job to initialise your database that you can skip on subsequent runs to scale your existing resources.

You can set this on a node in the template section where applicable. You can check skip node execution to skip a node or workflow, or switch the mode to enter an argument or function.

If the provided value resolves to true then the node will not be executed during the template run, if the value resolves to false then the node will execute as normal.

You can use template arguments, functions, and references to programmatically execute or skip nodes.

{
    "kind": "workflow",
    "skipNodeExecution": "${fn.eq(args.ENVIRONMENT, 'DEVELOPMENT')}",
    "spec": {}
}