Create a template

You can create a new template from the templates page within a project, or the templates page in your team or user account settings.

Templates are encrypted at rest on the platform, so any secrets and sensitive data are kept secure.

There are two ways to access your templates in the Northflank UI, either from your account page, or from within a project. These separate views are only to make it easier to navigate to relevant templates as all templates are stored on the account level.

Your account templates page will display all templates created within your account, regardless of any projects they may be related to.

The template page within a project will only show templates that have been created in the project, or run against that project.

If you delete a project which you have created templates in, the templates will still be available via your account templates page.

You can create a new project using a template, or choose an existing project for the template to run in. You can specify the name, colour, and region of the project to be created. The project region cannot be changed after creation. If your account or team uses another cloud provider, you can also choose from available clusters on your own cloud account.

If you run a template that creates a project with the same name as an existing project in the account, it will update the project according to the template. If the template specifies a region different to the existing project, the template run will fail.

If you run a template that specifies (but does not create) a project that doesn't exist in the account, the template run will fail.

You can configure argument overrides for a template which will override all arguments set in the template. Arguments can be accessed in the template in the form: ${args.argumentName}.

You can configure GitOps to manage your template from a repository, and how and when the template should run.

Run automatically

You can enable the template to run automatically whenever it is updated - whether it's updated in the Northflank UI, via the API, or changed in the Git repository (if GitOps is enabled).

GitOps

You can enable GitOps to sync the template with a Git repository. You can make changes to your template by committing changes to it in the repository or by editing it in Northflank, and it will be updated on the other platform.

This allows you to maintain your templates alongside your codebase, or in a separate infrastructure repository. Combined with Git triggers you can push changes to your code or template and automatically trigger a template run.

Learn more about GitOps on Northflank.

Concurrency

You can select a concurrency setting (under advanced) to manage how your templates handles more than one request to run.

• Allow (default): multiple template runs can be executed in parallel, with no restrictions
• Queue: each time a template run is triggered it will be added to a queue, and runs will be executed sequentially in order of creation
• Forbid: if a template is currently pending or running any run requests will be ignored

The template editor consists of a template options form and the template editor itself. You can edit a template using either the visual editor to drag and drop nodes, or edit the template code directly.

Create a template using the visual editor

The visual editor allows you to drag and drop nodes in the order you want them to run.

Nodes can be nested in workflow nodes, which define whether nodes contained run in sequence (sequential), or at the same time (parallel). Workflow nodes can be nested within other workflow nodes. You can click the button in the workflow node to switch between parallel and sequential workflows.

To add a node, find the relevant node from the list, or use the search box, and drag the node into your workflow. If a node is inserted into a sequential workflow, it will be placed before, between, or after other nodes depending on where it is dropped, with arrows showing the sequence the template will run in. Nodes dropped into a parallel workflow will be added without any sequence, as they will be executed simultaneously. You can drag and drop nodes to re-order them, or move them into and out of workflows.

Click on an individual node to edit that specific node. You can configure a node using the form, or switch to code to directly edit the JSON for the individual node. Editing the code directly is particularly useful to paste in resource specifications from your existing projects, or other sources.

Click save node to finish editing an individual node, cancel to discard your changes, or delete node to remove it.

Click create template or save template to save your template.

Create a template using the code editor

Template code consists of JSON defining resources and actions to be performed in workflows (either sequential or parallel), as per their API specifications. Learn more about writing templates here.

You can enter the content of your template using the Northflank code editor by selecting code. The editor includes code hints, autocompletion, and error checking to help you include required properties in the correct format.

Only the apiVersion and spec object, which contains the template workflow, are required when you are editing a template in the Northflank application, other properties such as the project are configured in the template options form. If you paste a template into the editor which includes these properties, they will be removed from the JSON and used to populate the form fields.

The initial empty template consists of the following:

{
  "apiVersion": "v1",
  "spec": {
    "kind": "Workflow",
    "spec": {
      "type": "parallel",
      "steps": []
    }
  }
}

You can add nodes, including workflow nodes, to the steps array in the workflow. You can also change the parent workflow to sequential if required.

You can switch to the visual editor to preview the template, and can continue to edit the template in the visual editor.