
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: []
apiVersionis alwaysargoproj.io/v1alpha1for Argo Workflows resources. Despite the "alpha" label, the API is stable and widely used in production.kindisWorkflow,WorkflowTemplate,ClusterWorkflowTemplateorCronWorkflow.metadataholds the name, namespace, labels and annotations.specdescribes 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
activeDeadlineSecondsfails the workflow when it runs too long.ttlStrategydeletes the workflow object after completion; separate values for success and failure let you keep failed runs longer for investigation.podGC.strategycan beOnPodCompletion,OnPodSuccess,OnWorkflowCompletionorOnWorkflowSuccess.parallelismlimits 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
suspendpauses until resumed or untildurationelapses.httpmakes an HTTP request from the Argo agent without starting a pod per call.containerSetruns 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
defaultare required. enumrestricts allowed values and renders a drop-down in the UI submit form.- Output parameters can read from a file
path, from ajsonPathorjqFilteron a resource, from a Kubernetessuppliedvalue, or from anexpression. valueFrom.defaultprotects 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.serviceAccountNameapplies to every pod, but a template can set its ownserviceAccountNamewhen one step needs extra permissions, such as a deploy step that patches Deployments. - Deadlines:
spec.activeDeadlineSecondslimits the entire run, while a template-levelactiveDeadlineSecondslimits 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,tolerationsandaffinityon 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
parallelismon a steps or DAG template caps only the children of that template. - Retries: there is no workflow-wide retry by default; set
retryStrategyon 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:
- YAML parsing. Indentation errors, tabs and unbalanced quotes fail immediately, before Kubernetes ever sees the object.
- 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.
- Argo validation. The controller and
argo lintcheck semantics: the entrypoint exists, referenced templates exist, inputs are declared, DAG dependencies form a graph without cycles, and expressions can be resolved. - Runtime evaluation. Some problems appear only during execution — for example, an output file that was never written, or a
withParamvalue 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
- Tabs instead of spaces — YAML forbids tabs for indentation.
- Wrong list nesting in steps — forgetting the second dash makes every step its own stage.
- Unquoted values starting with
{{— YAML interprets{as a mapping. Always quote:value: "{{item}}". - Numbers where strings are expected —
limit: 3is accepted, but quoting numeric strings such as"3"or"0.5"avoids type surprises in parameters. - Two types in one template — a template cannot have both
containerandscript. - Duplicate template names — names must be unique within a workflow.
- Missing
inputsdeclaration — referencing{{inputs.parameters.x}}requiresxto be declared in the template's inputs.
Troubleshooting YAML Errors
- Run
argo lint file.yamlto 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 applysucceeds butargo submitfails, 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
generateNamefor 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.



