Argo Workflows

Argo Workflows is a workflow engine that runs on Kubernetes and uses Kubernetes as its scheduler. A workflow is a YAML custom resource: a list of steps or a DAG of tasks, where each step runs as its own pod. It solves the problem of running multi-step jobs (builds, tests, batch processing, data pipelines) on a cluster without a separate CI server or job runner to keep alive.

What it is

The project is part of the Argo family under the CNCF, next to Argo CD (GitOps delivery), Argo Rollouts (progressive delivery) and Argo Events (event triggers). The licence is Apache 2.0. The code lives at argoproj/argo-workflows, and the community Helm chart lives in argoproj/argo-helm.

The current line is v4.1. v4.1.5 shipped on 2026-10-09, on the same day as v4.0.13, so two minor lines get patches in parallel. v3.7 still received a patch (v3.7.18) in August 2026. The Helm chart argo-workflows 2.0.13 ships app version v4.1.5.

v4.0 was a major release with removals. The fields deprecated in 3.6 are gone (schedule, mutex, semaphore, podPriority), the in-repo Python SDK is gone in favour of Hera, and the release manifests now carry full CRDs with validation, which must be applied with server-side apply.

The resource types:

• Workflow — one run. It holds the spec and, after it starts, the live status of every node.
• WorkflowTemplate and ClusterWorkflowTemplate — reusable definitions, scoped to a namespace or to the cluster. A Workflow can reference a whole template or call single templates from it.
• CronWorkflow — a Workflow on a schedule, with a list of cron expressions in schedules.
• WorkflowEventBinding — starts a template from an HTTP event that the Argo Server receives.

How it works

Two Deployments make up an install. The workflow controller reconciles Workflow resources: it watches them, decides which nodes can run next, and creates pods for them. The Argo Server serves the API and the web UI on port 2746, and the controller can run without it. Each step pod has a main container that runs the user's image, an init container that fetches input artifacts and parameters, and a wait container that saves outputs and artifacts when main exits. The argoexec binary inside those containers is the emissary executor, the only executor since v3.4. It needs no privileged access.

The controller processes one Workflow at a time per worker, and the full state of a run lives in the Workflow's status. Large workflows can make that status too big for one etcd object; the controller can offload node status to a database for this case. Completed Workflows can also be copied to Postgres or MySQL with the workflow archive, so history survives after the resources are deleted.

v4.1 adds an opt-in, beta init-less pod layout. With initlessPod.enabled: true on the controller, pods have no init containers. A supervisor container takes over the work of init and wait, and argoexec reaches main through a Kubernetes image volume. Image volumes are on by default from Kubernetes 1.36.

When to use it

Reach for it when:

• The jobs already run on Kubernetes and each step fits in a container image.
• A job is a DAG: fan-out, fan-in, conditionals with when, retries with backoff, loops over parameters.
• Builds must run on the cluster's own compute, without a hosted CI runner or a build daemon on a laptop.
• Steps pass files to each other through an artifact repository (S3, MinIO, GCS, Azure) or a shared volume.
• The same definition must run on demand, on a cron schedule, and from an HTTP event.

Skip it when:

• There is no Kubernetes cluster. The engine needs one, and a cluster only for CI is a large overhead.
• The job is one container on a schedule. A Kubernetes CronJob does that with no extra controller.
• The team wants hosted CI with a marketplace of actions. GitHub Actions or a similar service has less to operate.
• The pipeline is data-centric with backfills, sensors and per-task retries over date ranges. Airflow is built around those ideas.
• Steps are many tiny tasks that each run for under a second. A pod per step adds scheduling overhead to every one.

At a glance

Core concepts

• Template — the unit of work. Types are container, script, resource (create a Kubernetes object), suspend, http, steps and dag.
• Steps vs DAG — steps runs lists in sequence, with parallel items inside each list. dag declares tasks with depends and runs them as soon as their dependencies finish.
• Parameters — strings passed in with {{inputs.parameters.x}} and out with outputs.parameters. Expressions use {{= ...}}.
• Artifacts — files saved to the artifact repository and loaded into later steps.
• Synchronization — mutexes and semaphores (lists since v4.0) limit concurrent workflows or templates.
• TTL and pod GC — ttlStrategy deletes finished Workflows; podGC deletes finished pods.

Key facts

Item	Value
Current release	v4.1.5 (2026-10-09); v4.0.13 patched on the same day
Licence	Apache 2.0
Components	workflow-controller, argo-server, argoexec (emissary)
UI and API port	2746, HTTPS by default
Install methods	Release manifests (server-side apply), community Helm chart
Install scopes	Cluster, namespace, managed namespace
Server auth modes	client (default since v3.0), server, sso
Python SDK	Hera (the in-repo SDK was removed in v4.0)

Argo Workflows vs Tekton

Aspect	Argo Workflows	Tekton Pipelines
Unit	Workflow with templates	Task, Pipeline, and their Run objects
Step layout	One pod per step or DAG task	One pod per Task, steps as containers inside it
Flow control	DAG, steps, loops, when, recursion	DAG with runAfter, when expressions
UI	Built in (Argo Server)	Separate Tekton Dashboard
Scope	General workflows: CI, batch, data, ML	CI/CD building blocks

How to integrate

Install with the release manifests

ARGO_WORKFLOWS_VERSION="v4.1.5"
kubectl create namespace argo
kubectl apply --server-side -n argo \
  -f "https://github.com/argoproj/argo-workflows/releases/download/${ARGO_WORKFLOWS_VERSION}/quick-start-minimal.yaml"

kubectl -n argo port-forward service/argo-server 2746:2746
# open https://localhost:2746 (https, self-signed certificate)

The quick-start manifest is for trials. For a real install, use the install.yaml or namespace-install.yaml asset from the release page, and patch it with Kustomize.

Install with Helm

# values.yaml for the argo-workflows chart (2.0.x)
controller:
  workflowNamespaces:
    - argo
  workflowDefaults:
    spec:
      ttlStrategy:
        secondsAfterCompletion: 86400
      podGC:
        strategy: OnPodSuccess
server:
  authModes:
    - client
workflow:
  serviceAccount:
    create: true
    name: argo-workflow

helm repo add argo https://argoproj.github.io/argo-helm
helm install argo-workflows argo/argo-workflows \
  --namespace argo --create-namespace -f values.yaml

With the chart, the UI Service is argo-workflows-server, not argo-server.

A minimal build template

apiVersion: argoproj.io/v1alpha1
kind: WorkflowTemplate
metadata:
  name: image-build
  namespace: argo
spec:
  entrypoint: build
  serviceAccountName: argo-workflow
  arguments:
    parameters:
      - name: image   # e.g. registry.example.com/app:<git-sha>
  templates:
    - name: build
      inputs:
        parameters:
          - name: image
      container:
        image: moby/buildkit:v0.34.0
        command: [buildctl]
        args:
          - --addr=tcp://buildkitd.buildkit:1234
          - build
          - --frontend=dockerfile.v0
          - --local=context=/work
          - --local=dockerfile=/work
          - --output=type=image,name={{inputs.parameters.image}},push=true

Start a run with argo submit -n argo --from workflowtemplate/image-build -p image=registry.example.com/app:abc123 --watch. A real template also needs a clone step that fills /work; the project's examples/buildkit-template.yaml shows the full clone, build and push DAG.

In the GL stack

Argo Workflows v4.1.5 runs on the management cluster, one of three K3s clusters on the Mac. It is the build system for the container images behind builddaily.io, paiddaily.io and the other products.

• What it runs. There is one workflow per product image. Each workflow hands the build to BuildKit v0.34.0 on the same cluster, which keeps the layer cache and pushes the result to the private registry.
• Where images go. The registry is a CNCF Distribution registry on the management cluster that every cluster can reach. Images are tagged by git SHA, so a tag always points at one commit.
• Why it was chosen. It replaced local image builds in Docker Desktop. Builds now run on cluster compute next to the registry, and the Argo UI is published on the Mac to watch and retry runs.
• Where delivery happens. Argo Workflows only builds and pushes. Argo CD on the same cluster delivers the manifests to the beta and prod clusters from Git, so build and deploy are separate steps.

Gotchas

• v4.0 removed old fields. CronWorkflows with schedule, and workflows with mutex, semaphore or podPriority, need the list forms (schedules, mutexes, semaphores) or podPriorityClassName. argo convert rewrites all of them except podPriority.
• Full CRDs need server-side apply. Since v4.0 the CRDs are too large for client-side kubectl apply. Use --server-side, or the CRD installer image if the tooling cannot do it.
• Skipped outputs now fail loudly. From v4.0.7 (and v3.7.16), a reference to the output of a skipped or omitted step fails the node unless a valueFrom.default, an input default or a ?? fallback handles it. An output expression that returns nil also fails, where it used to produce the string <nil>.
• SSO logout on v4.1.2. The session token format changed, so every SSO user logs in again once after the upgrade, and tokens saved from argo auth token must be fetched again.
• The UI is HTTPS on 2746. Plain http:// gets a server error. The default certificate is self-signed.
• Set TTL and pod GC. Without ttlStrategy and podGC, finished Workflows and pods stay in the cluster and the controller keeps watching them.
• The emissary caches image commands by tag. If a step has no command, the controller looks up the image's entrypoint and caches it by image and tag. Rebuild an image with a new entrypoint under the same tag and steps can run the old command. Set command explicitly, or use a new tag.

Risks

• Licence and governance. Apache 2.0 under CNCF governance. The licence risk is low.
• Release pace. Two minor lines get patches at the same time, and v4.0 and v4.1 both had behaviour changes inside patch releases (v4.0.7, v4.1.2). Read the upgrading guide before every patch, not only before a minor.
• Lock-in. Workflow YAML is specific to Argo. The container images move easily; the DAGs, parameters and templates do not move to another engine.
• Security. Each step runs with the workflow's service account. A build step that can push images, or a resource template that can create objects, has real power. Give workflows a narrow service account, and keep the Argo Server behind authentication.
• Cluster load. Each step is a pod, and the full run state is in one resource. Very wide workflows put load on the API server and etcd.

Alternatives

• Tekton Pipelines — pick it for CI/CD building blocks on Kubernetes with Tekton's Task catalog and Tekton Chains for supply-chain signing.
• GitHub Actions — pick it when the code is on GitHub and the team does not want to operate a build cluster.
• Apache Airflow — pick it for scheduled data pipelines that need backfills, sensors and a Python DAG API.
• Kubernetes Jobs and CronJobs — pick them for single-container tasks with no dependencies between steps.

Related

• BuildKit and the private registry — the builder the workflows call and the place the images land.
• Argo CD — the delivery half: it syncs the manifests that use the built images.
• K3s, Lima and Rancher — the cluster, the VMs and the management plane under it.
• MinIO and Postgres — the kinds of store Argo uses for an artifact repository and the workflow archive.
• Airflow — the scheduler for data pipelines in the same stack.
• Official: Argo Workflows docs, releases, upgrading guide, argo-helm chart.