Workflow Automation

How Is an Argo Workflows YAML File Structured?

Understand every important field in Argo Workflows YAML — metadata, spec, templates, inputs, outputs, variables, expressions, retries, deadlines, garbage collection and synchronisation.

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

Argo Workflows is configured entirely in YAML. Once you understand how a manifest is structured — and which fields belong at workflow level versus template level — writing new pipelines becomes routine. This reference walks through a Workflow manifest from top to bottom, explains the purpose of each important field, shows the variable and expression syntax, and highlights the mistakes that cause most validation errors.

Use it alongside the YAML generator, which produces valid skeletons, and the YAML validator, which checks your edits.

The Overall Shape of a Workflow Manifest

Every manifest has four top-level keys, just like any Kubernetes object:

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: report-
  namespace: argo
  labels:
    team: analytics
spec:
  entrypoint: main
  arguments: {}
  templates: []
  • apiVersion is always argoproj.io/v1alpha1 for Argo Workflows resources. Despite the "alpha" label, the API is stable and widely used in production.
  • kind is Workflow, WorkflowTemplate, ClusterWorkflowTemplate or CronWorkflow.
  • metadata holds the name, namespace, labels and annotations.
  • spec describes the workflow itself.

Metadata Fields

name vs generateName

name sets an exact name, so a second submission with the same name fails because the object already exists. generateName adds a random suffix to a prefix, which is what you want for workflows submitted repeatedly. WorkflowTemplates and CronWorkflows use fixed names because they are long-lived definitions.

Labels and Annotations

Labels are indexed and used for filtering in the UI and CLI (argo list -l team=analytics). Annotations are free-form metadata. A useful convention is to label every workflow with team, application and environment so cost and ownership reports are straightforward. The annotation workflows.argoproj.io/description is shown in the UI, which is a convenient way to document intent.

Workflow-Level Spec Fields

The following fields live directly under spec and apply to the whole workflow.

entrypoint

The name of the template that runs first. It must exactly match a template's name. A mismatch is one of the most common validation errors.

arguments

Workflow-level parameters and artifacts. These can be overridden at submission with -p name=value or --parameter-file. They are available everywhere as {{workflow.parameters.name}}.

serviceAccountName

The Kubernetes service account used by every pod in the workflow unless a template overrides it. This determines what the pods can do in the cluster, so treat it as a security boundary.

Deadlines, Cleanup and Concurrency

spec:
  activeDeadlineSeconds: 7200
  ttlStrategy:
    secondsAfterCompletion: 86400
    secondsAfterSuccess: 3600
    secondsAfterFailure: 172800
  podGC:
    strategy: OnPodCompletion
  parallelism: 5
  • activeDeadlineSeconds fails the workflow when it runs too long.
  • ttlStrategy deletes the workflow object after completion; separate values for success and failure let you keep failed runs longer for investigation.
  • podGC.strategy can be OnPodCompletion, OnPodSuccess, OnWorkflowCompletion or OnWorkflowSuccess.
  • parallelism limits how many pods of this workflow run concurrently.

Other Useful Spec Fields

Field Purpose
onExit Template that always runs at the end
hooks Lifecycle hooks triggered by expressions or on exit
volumes / volumeClaimTemplates Shared storage for all pods
nodeSelector, tolerations, affinity Default scheduling constraints
podMetadata Labels and annotations added to every pod
securityContext Default pod security context
imagePullSecrets Registry credentials
priority Ordering among pending workflows
synchronization Mutexes and semaphores limiting concurrent workflows
workflowTemplateRef Run a stored WorkflowTemplate instead of inline templates
artifactRepositoryRef Choose a named artifact repository

Templates in Detail

spec.templates is a list. Each template has a name and exactly one type field.

Container Templates

- name: build
  container:
    image: golang:1.23
    command: [go, build, ./...]
    workingDir: /src
    env:
      - name: CGO_ENABLED
        value: "0"
    resources:
      requests: {cpu: 500m, memory: 512Mi}
      limits: {memory: 1Gi}

The container block accepts the same fields as a Kubernetes container: image, command, args, env, envFrom, resources, volumeMounts, securityContext and so on.

Script Templates

Script templates add a source field to a container definition. Argo writes the source to a file and runs it with the given command. Standard output is captured as outputs.result.

Resource Templates

resource templates create, apply, patch, replace or delete Kubernetes objects. successCondition and failureCondition use label-selector-style expressions against the object's fields, which lets a workflow wait for another controller to finish its work.

Suspend, HTTP and Container Sets

  • suspend pauses until resumed or until duration elapses.
  • http makes an HTTP request from the Argo agent without starting a pod per call.
  • containerSet runs several containers in a single pod with dependencies between them, which avoids pod start-up overhead for tightly coupled steps.

Steps and DAG Templates

Orchestration templates reference other templates by name. Steps use nested lists, DAGs use tasks with depends. Both support arguments, when, withItems, withParam, withSequence, continueOn and per-call hooks.

Inputs and Outputs

- name: transform
  inputs:
    parameters:
      - name: date
      - name: mode
        default: incremental
        enum: [incremental, full]
    artifacts:
      - name: raw
        path: /data/raw.csv
  outputs:
    parameters:
      - name: rows
        valueFrom:
          path: /tmp/rows
          default: "0"
    artifacts:
      - name: clean
        path: /data/clean.csv
  container:
    image: python:3.12-slim
    command: [python, /app/transform.py]
  • Input parameters without default are required.
  • enum restricts allowed values and renders a drop-down in the UI submit form.
  • Output parameters can read from a file path, from a jsonPath or jqFilter on a resource, from a Kubernetes supplied value, or from an expression.
  • valueFrom.default protects consumers when a value might be missing.

Variables and Expressions

Argo supports two syntaxes inside double braces.

Simple Tags

Tags like {{inputs.parameters.date}} or {{workflow.name}} are substituted as plain text. Commonly used variables include:

  • {{workflow.name}}, {{workflow.namespace}}, {{workflow.uid}}
  • {{workflow.parameters.<name>}}
  • {{workflow.creationTimestamp}} and formatted variants
  • {{steps.<step>.outputs.parameters.<name>}} and {{steps.<step>.outputs.result}}
  • {{tasks.<task>.outputs.parameters.<name>}} in DAGs
  • {{item}} and {{item.<field>}} inside loops
  • {{retries}} — the current retry attempt
  • {{pod.name}} inside a template

Expression Tags

Tags beginning with = are evaluated with the expr language, which supports operators, functions and Sprig helpers:

args: ["{{=sprig.upper(inputs.parameters.env)}}"]
when: "{{=asInt(steps.count.outputs.result) > 100}}"

Use expression tags when you need maths, string functions or JSON parsing. Use simple tags everywhere else; they are easier to read.

Retry Strategy Reference

retryStrategy:
  limit: "3"
  retryPolicy: OnTransientError
  backoff:
    duration: "30s"
    factor: "2"
    maxDuration: "10m"
  affinity:
    nodeAntiAffinity: {}
  expression: "lastRetry.status == 'Error'"

nodeAntiAffinity asks Kubernetes to schedule the retry on a different node, which helps when a node is unhealthy. expression gives fine-grained control over which failures are retried, using variables such as lastRetry.exitCode and lastRetry.message.

Synchronisation

From version 4.0 only the plural forms are supported:

spec:
  synchronization:
    mutexes:
      - name: deploy-production
    semaphores:
      - configMapKeyRef:
          name: argo-semaphores
          key: database-jobs

A mutex allows one holder at a time; a semaphore allows as many holders as the value stored in the referenced ConfigMap key. Both can also be set on individual templates.

Workflow-Level vs Template-Level Settings

Many settings can be declared in more than one place, and knowing which one wins prevents confusing behaviour. The general rule is that the most specific setting applies: a value on a template overrides the same value on the workflow spec, and a value on the workflow spec overrides the controller's workflowDefaults.

  • Service accounts: spec.serviceAccountName applies to every pod, but a template can set its own serviceAccountName when one step needs extra permissions, such as a deploy step that patches Deployments.
  • Deadlines: spec.activeDeadlineSeconds limits the entire run, while a template-level activeDeadlineSeconds limits just that step. Use both: a generous workflow deadline as a safety net and tight step deadlines where you know the expected duration.
  • Scheduling: nodeSelector, tolerations and affinity on the spec set defaults; a GPU training template can override them to land on GPU nodes while other steps stay on cheaper hardware.
  • Parallelism: the workflow-level value caps all pods, while a template-level parallelism on a steps or DAG template caps only the children of that template.
  • Retries: there is no workflow-wide retry by default; set retryStrategy on templates, or on the spec to apply it to every template.

How Argo Validates a Manifest

Validation happens in layers, and understanding them helps you read error messages:

  1. YAML parsing. Indentation errors, tabs and unbalanced quotes fail immediately, before Kubernetes ever sees the object.
  2. Schema validation. With full CRDs installed, the Kubernetes API server rejects unknown fields and wrong types, such as a string where a list is expected.
  3. Argo validation. The controller and argo lint check semantics: the entrypoint exists, referenced templates exist, inputs are declared, DAG dependencies form a graph without cycles, and expressions can be resolved.
  4. Runtime evaluation. Some problems appear only during execution — for example, an output file that was never written, or a withParam value that is not valid JSON.

Our validator covers layers one and three in your browser, which catches the majority of mistakes before you touch a cluster.

A Fully Annotated Example

The following manifest combines many of the fields described above. Comments explain each choice:

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: nightly-report-      # unique name per run
  labels: {team: analytics, env: prod}
spec:
  entrypoint: main                    # first template to run
  serviceAccountName: report-runner   # least-privilege identity
  activeDeadlineSeconds: 5400         # whole run must finish in 90 minutes
  ttlStrategy: {secondsAfterSuccess: 3600, secondsAfterFailure: 259200}
  podGC: {strategy: OnPodSuccess}     # keep failed pods for debugging
  arguments:
    parameters: [{name: date, value: "{{workflow.creationTimestamp.Y}}-{{workflow.creationTimestamp.m}}-{{workflow.creationTimestamp.d}}"}]
  templates:
    - name: main
      dag:
        tasks:
          - {name: extract, template: run, arguments: {parameters: [{name: cmd, value: extract}]}}
          - {name: report, template: run, depends: extract, arguments: {parameters: [{name: cmd, value: report}]}}
    - name: run
      inputs: {parameters: [{name: cmd}]}
      retryStrategy: {limit: "2", retryPolicy: OnError}
      container:
        image: ghcr.io/example/reporting:2.3.1
        args: ["{{inputs.parameters.cmd}}", "--date", "{{workflow.parameters.date}}"]
        resources: {requests: {cpu: 250m, memory: 256Mi}, limits: {memory: 512Mi}}

Notice how orchestration lives in main while the actual work is a single reusable run template. That separation keeps manifests short even as pipelines grow.

Keeping Large Manifests Maintainable

As pipelines grow, manifests can stretch to hundreds of lines. Three habits keep them manageable. First, move shared templates into WorkflowTemplates and call them with templateRef, so each manifest contains only what is unique to it. Second, use a consistent order inside every template — name, inputs, outputs, policies, then the container — so readers always know where to look. Third, run a formatter before committing so indentation and quoting are uniform and diffs only show meaningful changes.

Common YAML Mistakes

  1. Tabs instead of spaces — YAML forbids tabs for indentation.
  2. Wrong list nesting in steps — forgetting the second dash makes every step its own stage.
  3. Unquoted values starting with {{ — YAML interprets { as a mapping. Always quote: value: "{{item}}".
  4. Numbers where strings are expected — limit: 3 is accepted, but quoting numeric strings such as "3" or "0.5" avoids type surprises in parameters.
  5. Two types in one template — a template cannot have both container and script.
  6. Duplicate template names — names must be unique within a workflow.
  7. Missing inputs declaration — referencing {{inputs.parameters.x}} requires x to be declared in the template's inputs.

Troubleshooting YAML Errors

  • Run argo lint file.yaml to get the controller's own validation messages before submitting.
  • When an error mentions a path such as templates.main.steps[1].process, count the stages from zero.
  • If kubectl apply succeeds but argo submit fails, the YAML is syntactically valid but semantically wrong — check references and template names.
  • Paste the manifest into our validator to find structural errors and into the formatter to normalise indentation.

Frequently Asked Questions

Can I use JSON instead of YAML?

Yes. Kubernetes accepts JSON manifests, and the CLI does too. YAML is preferred because it is easier to read and supports comments.

Where is the full specification?

The official field reference is generated from the API and published in the Argo Workflows documentation. With full CRDs installed, kubectl explain workflow.spec also works.

How do I reuse YAML across workflows?

Use WorkflowTemplates and templateRef, rather than YAML anchors, so that shared logic is versioned in the cluster.

What is the difference between args and command?

They map directly to Kubernetes container fields. command overrides the image's entrypoint, and args overrides its default arguments. If you set only args, the image's own entrypoint receives them, which is often what you want for purpose-built tool images.

Can I comment out a template temporarily?

Yes, YAML comments start with #. Remember that commenting out a template that other steps reference will make validation fail until those references are removed too.

Does indentation style matter?

Only consistency matters. Two spaces per level is the community convention.

Key Takeaways

  • Every template has a name and exactly one type.
  • The most specific setting wins: template over workflow over controller defaults.
  • Quote every value that begins with double curly braces.
  • Use generateName for workflows and fixed names for templates and CronWorkflows, and pin image tags everywhere.

Conclusion

A workflow manifest is a predictable structure: metadata, a spec with workflow-wide behaviour, and a list of single-purpose templates connected through inputs, outputs and expressions. Keep this reference open while writing your next pipeline, and explore WorkflowTemplates to start sharing that YAML across teams.

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.