Workflow Templates

How Do You Create Reusable Argo Workflows Templates?

Learn how to build reusable Argo Workflows templates. Covers WorkflowTemplate, ClusterWorkflowTemplate, templateRef, workflowTemplateRef, parameters, versioning and GitOps best practices.

10 min read 2,009 wordsUpdated By Argo Workflows Editorial Team

The word "template" means two different things in Argo Workflows, and that is the first source of confusion for new users. Inside a workflow, a template is a single unit of work such as a container or a DAG. At the cluster level, a WorkflowTemplate is a stored, reusable workflow definition. This guide focuses on the second meaning — how to build a library of reusable workflow definitions that teams can submit, compose and version safely — while clarifying how both meanings connect.

Why Reusable Templates Matter

Without stored templates, every pipeline is a standalone YAML file. Teams copy and paste the same "build image" or "notify Slack" logic into dozens of workflows, and every fix must be applied everywhere. WorkflowTemplates solve this in three ways:

  • Single source of truth: shared steps live in one object, so fixes and upgrades happen once.
  • Self-service submission: users can launch a stored template from the UI or CLI with a form for its parameters, without touching YAML.
  • Composition: workflows call individual templates from a WorkflowTemplate with templateRef, assembling pipelines from tested building blocks.

The Template Kinds Compared

Kind Scope Typical use
Workflow One execution A single run, created by a person, a CronWorkflow or an event
WorkflowTemplate Namespace Reusable pipelines and steps owned by a team
ClusterWorkflowTemplate Cluster Organisation-wide building blocks shared across namespaces
CronWorkflow Namespace A schedule that creates Workflows from a spec or template

Creating a WorkflowTemplate

A WorkflowTemplate uses the same spec as a Workflow. The only structural differences are the kind and the use of a fixed name:

apiVersion: argoproj.io/v1alpha1
kind: WorkflowTemplate
metadata:
  name: build-and-push
  namespace: ci
  annotations:
    workflows.argoproj.io/description: Build a container image with Kaniko and push it
spec:
  entrypoint: main
  serviceAccountName: ci-builder
  arguments:
    parameters:
      - name: repo
      - name: image
      - name: tag
        value: latest-dev
  templates:
    - name: main
      steps:
        - - name: build
            template: kaniko
            arguments:
              parameters:
                - {name: repo, value: "{{workflow.parameters.repo}}"}
                - {name: destination, value: "{{workflow.parameters.image}}:{{workflow.parameters.tag}}"}
    - name: kaniko
      inputs:
        parameters:
          - name: repo
          - name: destination
      container:
        image: gcr.io/kaniko-project/executor:v1.23.2
        args:
          - "--context={{inputs.parameters.repo}}"
          - "--destination={{inputs.parameters.destination}}"
        resources:
          requests: {cpu: "1", memory: 2Gi}

Apply it like any other resource:

kubectl apply -n ci -f build-and-push.yaml
argo template list -n ci

The argo template create command also works, and argo template lint validates the file first.

Three Ways to Use a WorkflowTemplate

1. Submit It Directly

argo submit -n ci --from workflowtemplate/build-and-push \
  -p repo=git://github.com/example/api.git \
  -p image=registry.example.com/api \
  -p tag=1.9.0 --watch

The CLI creates a new Workflow whose workflowTemplateRef points at the template. The UI offers the same with a "Submit" button and a parameter form.

2. Reference the Whole Template From a Workflow

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: api-build-
  namespace: ci
spec:
  workflowTemplateRef:
    name: build-and-push
  arguments:
    parameters:
      - {name: repo, value: "git://github.com/example/api.git"}
      - {name: image, value: registry.example.com/api}

The workflow inherits the template's entire spec. Fields set in the Workflow, such as arguments, labels or activeDeadlineSeconds, are merged on top. This is the pattern used by CronWorkflows and by Argo Events sensors to launch stored pipelines.

3. Call a Single Template With templateRef

- name: release
  steps:
    - - name: image
        templateRef:
          name: build-and-push
          template: kaniko
        arguments:
          parameters:
            - {name: repo, value: "git://github.com/example/web.git"}
            - {name: destination, value: "registry.example.com/web:2.0.0"}

templateRef borrows one named template, here kaniko, from the stored object. The calling workflow supplies arguments and runs the step as if it were defined locally. This is the most powerful composition mechanism because it lets you build new pipelines from proven parts.

ClusterWorkflowTemplates

When a building block is useful to every team — security scanning, notifications, artifact promotion — publish it once at cluster scope:

apiVersion: argoproj.io/v1alpha1
kind: ClusterWorkflowTemplate
metadata:
  name: notify
spec:
  templates:
    - name: slack
      inputs:
        parameters:
          - name: text
      container:
        image: curlimages/curl:8.10.1
        command: [sh, -c]
        args:
          - >
            curl -fsS -X POST -H 'Content-Type: application/json'
            --data "{\"text\": \"{{inputs.parameters.text}}\"}" "$WEBHOOK"
        env:
          - name: WEBHOOK
            valueFrom:
              secretKeyRef: {name: slack-webhook, key: url}

Reference it with clusterScope: true:

templateRef:
  name: notify
  template: slack
  clusterScope: true

Note that the Secret slack-webhook is resolved in the namespace where the workflow runs, not where the template was defined, because ClusterWorkflowTemplates have no namespace. Each consuming namespace must therefore provide its own copy of the secret, which is actually a useful security property: teams cannot read each other's credentials.

Designing Template Parameters

Good parameters make templates easy and safe to use:

  1. Give sensible defaults for optional values so most callers pass only what matters.
  2. Use enum for constrained values such as environments; the UI renders a drop-down.
  3. Add descriptions with the description field on parameters so the submit form explains each one.
  4. Validate early. A first step that checks parameter combinations fails fast with a clear message instead of failing deep in the pipeline.
  5. Avoid secret parameters. Pass the name of a Secret, not its value.
arguments:
  parameters:
    - name: environment
      value: staging
      enum: [dev, staging, production]
      description: Target environment for the deployment

Versioning Strategies

Because templates are referenced by name, changing a template changes every pipeline that uses it. Choose a strategy deliberately.

Strategy A: Version in the Name

Publish build-and-push-v1 and build-and-push-v2 side by side. Consumers upgrade explicitly by changing the reference. This is the safest option for widely shared ClusterWorkflowTemplates.

Strategy B: Single Name, Git-Controlled Changes

Keep one name and treat every change like an API change: backwards-compatible additions only, reviewed in pull requests, deployed through Argo CD. This works well for team-owned templates with few consumers.

Strategy C: Semantic Labels

Label templates with a version and a stability channel, and document which channel each consuming pipeline should use. It requires discipline but keeps names stable.

Whatever you choose, remember that a running workflow resolves template references when it starts and stores the result in its status, so changing a template does not affect workflows that are already running.

Building a Template Library: A Practical Layout

Most organisations end up with three layers of templates. Planning for them from the start keeps the library tidy as it grows.

Layer 1: Primitive Building Blocks

These are small, single-purpose templates published as ClusterWorkflowTemplates by the platform team: send a notification, build an image, scan an image, copy files between buckets, run a database migration, wait for a Kubernetes resource. Each one has a narrow interface, clear parameters and strong tests. Application teams never edit them; they only call them with templateRef.

Layer 2: Team Pipelines

Each team composes primitives into WorkflowTemplates in its own namespace: "build, test and publish the API", "refresh the analytics mart", "retrain the recommendation model". These templates encode the team's process and usually have an entrypoint so they can be submitted directly or scheduled.

Layer 3: Triggers

CronWorkflows, Argo Events sensors and CI jobs sit on top and decide when team pipelines run. They contain almost no logic of their own — just a schedule or event, a workflowTemplateRef and the arguments for that particular invocation.

This layering gives each group a clear responsibility. The platform team owns reliability and security of primitives, application teams own their process, and triggers stay trivial to review.

Testing Templates Before You Publish Them

A broken shared template can break dozens of pipelines at once, so test templates as carefully as application code:

  1. Lint in CI. argo template lint validates structure and references on every pull request.
  2. Unit-test the container logic. The image a template runs should have its own tests independent of Argo.
  3. Run an integration workflow. Apply the changed template to a test namespace and submit a small workflow that calls it with representative parameters. Fail the pull request if that workflow fails.
  4. Check backwards compatibility. If existing consumers pass parameters that you renamed or removed, their next run will fail. Keep old parameters working, or publish a new version.
  5. Document changes. A short changelog in the template's annotations or repository helps consumers understand what changed and why.

Teams that adopt this routine rarely suffer surprise breakages from shared templates, even with hundreds of consumers.

Managing Templates With GitOps

Store templates in Git, one file per template, organised by namespace. Sync them with Argo CD or Flux. Add CI that runs argo lint on every pull request, and optionally submit changed templates to a test namespace with sample parameters. This gives you code review, an audit trail and instant rollback for pipeline changes — the same guarantees application code enjoys.

Workflow-Level Defaults in Templates

Everything you can put in a Workflow spec can also live in a WorkflowTemplate, and that makes templates an excellent place to encode operational standards. A team pipeline template can include activeDeadlineSeconds, ttlStrategy, podGC, labels for cost reporting, a default serviceAccountName, node selectors and an onExit notification. Every run created from the template inherits those settings automatically, so authors of individual runs cannot forget them.

When a Workflow references a template with workflowTemplateRef, fields set on the Workflow are merged over the template's spec. That lets a caller extend a deadline or add a label for a special run without editing the shared template. Be aware that merging works at field level: setting arguments.parameters on the Workflow supplies values for the template's parameters, but providing a completely different templates list is not supported when a template reference is used.

Template Naming Conventions

Clear names make a library discoverable. A few conventions that scale well:

  • Use verbs for primitives: build-image, scan-image, send-slack, copy-s3.
  • Use nouns for pipelines: api-release, orders-etl, churn-model-training.
  • Add a version suffix only to templates consumed by many teams, as described above.
  • Keep names inside a template short and descriptive, because they appear in node names and expressions.

Combined with description annotations, these conventions let new team members browse the template list in the UI and understand what is available without asking.

Security Considerations

  • Templates run with the service account set in the template or calling workflow. Do not set powerful service accounts inside shared templates unless every consumer should have that power.
  • The controller option templateReferencing: Strict forces all workflows to use stored templates, which prevents users from submitting arbitrary inline YAML. Secure mode additionally snapshots the template at submission so later edits cannot change a running workflow's behaviour.
  • Limit who can create or update ClusterWorkflowTemplates with RBAC; they affect every namespace.

Troubleshooting Templates

  • workflowtemplates.argoproj.io "x" not found — the template is in a different namespace. WorkflowTemplates are namespace-scoped; use a ClusterWorkflowTemplate for cross-namespace reuse.
  • template x not found in workflow template y — the template field in templateRef does not match a template name inside the stored object.
  • Missing parameter errors when submitting — required parameters without values must be supplied with -p.
  • ClusterWorkflowTemplate reference fails — clusterScope: true is missing from templateRef.
  • Changes not picked up — the workflow started before you applied the change; resubmit it.

Frequently Asked Questions

Can a WorkflowTemplate reference another WorkflowTemplate?

Yes. Templates can use templateRef to call templates from other stored objects, which lets you build layered libraries.

Can I run a ClusterWorkflowTemplate directly?

Yes, with argo submit --from clusterworkflowtemplate/<name>, provided you have permission in the target namespace.

Do WorkflowTemplates need an entrypoint?

Only if they will be submitted directly or referenced with workflowTemplateRef. Library templates used purely through templateRef can omit it.

How do I build templates quickly?

Use our Workflow Template Builder to assemble container and script templates visually and download valid YAML.

Key Takeaways

  • WorkflowTemplates are namespace-scoped; ClusterWorkflowTemplates are shared across namespaces.
  • Use workflowTemplateRef to run a whole template and templateRef to borrow a single step.
  • Design parameters with defaults, enums and descriptions so the UI form is self-explanatory.
  • Pick a versioning strategy before templates have many consumers.
  • Lint, test and review template changes like application code.
  • Restrict who can modify shared templates with RBAC and template referencing modes.
  • Layer your library: platform primitives at cluster scope, team pipelines in namespaces, and thin triggers such as CronWorkflows and sensors on top. Document every template with a description annotation so the UI explains what it does.

Conclusion

WorkflowTemplates and ClusterWorkflowTemplates turn Argo Workflows into a platform of reusable building blocks. Define clear parameters, choose a versioning strategy, manage everything through Git and restrict who can change shared templates. Then schedule your stored pipelines with the CronWorkflow guide. A well-organised template library is one of the highest-leverage investments a platform team can make, because every improvement to a shared building block immediately benefits every pipeline that uses it, across every team in the organisation.

Argo Workflows Editorial Team

Written and reviewed according to our editorial policy. Spotted an error? Tell us and we will fix it. This site is independent and not affiliated with the Argo Project.