Templates

Pipekit enhances the Workflow Templates functionality of Argo Workflows by allowing you to version control your Workflow Templates and share them across multiple clusters.

The Templates documentation can be followed for both Cluster Workflow Templates and Workflow Templates. To simplify things, "Workflow Templates" will be used throughout the documentation, but unless specified, will refer to both.

For further information on Workflow Templates, see the Argo Workflows documentation. For a worked example that uses a Template to scope a Terraform apply step to authorized users, see the Infrastructure as Code with OpenTofu use case.

Creating a Workflow Template

You can create your Workflow Templates in the usual manner. However, once you have written them you do not need to apply them to your cluster. Instead, you need to add them to your git repo and to make Pipekit aware of the Workflow Template. Pipekit will then manage the lifecycle of the Workflow Template in your cluster(s).

Adding a Workflow Template to Pipekit

Go to the Templates tab in Pipekit and click on the + Add workflow templates button.

Choose the organization, git repository and path of the Workflow Template within the git repository. You can also add a human-friendly name and description for the Workflow Template.

Bulk adding Workflow Templates to Pipekit

If you have multiple Workflow Templates in the same directory within a git repository, tick Include templates from folder, define the path to the folder, and Pipekit will bulk import your Workflow Templates.

Editing a Workflow Template in Pipekit

You can edit the name and description of your Workflow Template in Pipekit. Click the Workflow Template you want to edit and go to the Settings tab. Click the Edit button.

Deleting a Workflow Template from Pipekit

You can delete a Workflow Template from Pipekit by clicking on the Workflow Template you wish to delete and going to the Settings tab. Click the Delete button.

Submitting a Workflow Template

Submitting a standalone template

Go to the Templates tab in Pipekit, find the Workflow Template you wish to submit to your cluster and click the radio button next to it. Then click the Submit button.

You then need to choose the cluster you wish to submit the Workflow Template to, as well as the template version.

After this, you have the option to choose the namespace you wish to run your Workflow Template in and you can choose the entrypoint. Finally, if your Workflow Template had global parameters set, you can set the values for these parameters prior to submitting the Workflow Template.

Once you have pressed Submit, Pipekit will apply the Workflow Template to your cluster. A link will be presented allowing you to watch the Pipe run.

Submitting a Workflow Template as part of a Pipe

You can reference one or more Workflow Template(s) as part of a regular workflow using templateRef in your workflow spec. For example:

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: example-wf-
spec:
  entrypoint: main
  templates:
  - name: main
    dag:
      tasks:
        - name: run-workflow-template
          templateRef:
            name: my-workflow-template
            template: main

Workflow Templates version control

Pipekit will automatically track changes to your Workflow Templates. You can make new versions by creating a git tag in your git repository. Pipekit will automatically detect the new version and update the Workflow Template in Pipekit. Pipekit also makes the latest version of your Workflow Template available to use by tracking your default repository branch (typically this is main).

You can view all the versions of a template by clicking on the template in the Templates tab in Pipekit and selecting the version you wish to view.

Pinning a Workflow Template version

If you have a workflow that references a Workflow Template, you can pin the version of the Workflow Template that the workflow uses. This means that if you make changes to the Workflow Template, the workflow will not be affected. To pin a Workflow Template version, you can use the pipekit-io-templates-gitRef label in your workflowMetadata. For example:

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: wf-name-
spec:
  entrypoint: main
  workflowMetadata:
    labels:
      pipekit-io-templates-gitRef: v1.0.1
...

The above example will apply globally to all Workflow Templates referenced by the workflow.

You can override the template version at the template level too:

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
name: wf-name
spec:
entrypoint: main
workflowMetadata:
  labels:
    pipekit-io-templates-gitRef: v1.0.1
arguments:
  parameters:
    - name: global-parameter
      value: hello
templates:
  - name: main
    arguments:
      parameters:
        - name: message
          value: "{{workflow.parameters.global-parameter}}"
        - name: pipekit-io-templates-gitRef
          value: "v1.0.2"
    templateRef:
      name: whalesay-template
      template: whalesay
  - name: another-whalesay
    arguments:
      parameters:
        - name: message
          value: "{{workflow.parameters.global-parameter}}"
    templateRef:
      name: whalesay-template
      template: whalesay
    ...

In the above example, the workflow will use v1.0.1 of the Workflow Template globally, so the another-whalesay task will use version v1.0.1 of the referenced template, but the whalesay task will use version v1.0.2 of the Workflow Template.