2026.10.19 インフラ・クラウド

Argo Workflowsとは？DAG・WorkflowTemplate・CronWorkflowのYAML実装とArgo CDとの役割分担【v4.1系】

Q: v3系からv4系へ上げるときに何を確認すればよいですか？

確認の起点は、Upgrading Guideに記載された破壊的変更です。CronWorkflowの単数形 schedule 、Workflowの podPriority ・単数形の mutex と semaphore はv4.0で削除されたので、手元のYAMLを検索して該当箇所を置き換える必要があります。旧Python SDKを使っている場合は、Heraへの移行も必要です。CRDの適用は --server-side で行います。v4.1ではargo archiveコマンドが名前でも指定できるようになりました。

Q: Kubernetesの知識はどの程度必要ですか？

Pod・Namespace・ServiceAccountとRBACの意味が分かり、 kubectl でログや状態を追えれば、検証環境で動かすところまでは進められます。本番運用ではこれに加えて、ステップのPodに付ける権限の絞り込み、リソース要求の設定、コントローラーの監視が必要です。ワークフローの失敗の多くはPodの起動失敗やイメージ取得失敗として現れるため、Kubernetes側の切り分けができる人を1人は置いておくべきです。

Argo Workflowsとは？DAG・WorkflowTemplate・CronWorkflowのYAML実装とArgo CDとの役割分担【v4.1系】

Argo Workflowsは、Kubernetesのカスタムリソース（CRD）として動き、ワークフローの各ステップを1つのPodとして実行するオープンソースのワークフローエンジンです。この記事では、v4.1系（2026年10月時点）を検証環境に入れてhello-worldを流す手順、DAGとWorkflowTemplateで依存関係つきのジョブを組むYAML、CronWorkflowでの定期実行とリトライ設計を、公式ドキュメントに沿ってコード付きで示します。あわせて、v4.0で入った破壊的変更、同じArgoプロジェクトのArgo CDとの役割分担、AirflowやTektonとの使い分けまで、導入の判断材料をまとめました。

まとめ：Argo Workflowsの仕組みと導入判断を先に押さえる要点

Argo Workflowsは「終わりのあるジョブを、コンテナの組み合わせとして順序どおりに流す」ための道具です。ワークフローはYAMLで宣言し、ステップを直列に並べるstepsか、依存関係をグラフで書くDAGのどちらかで組みます。各ステップがPodになるので、言語やライブラリの違いをコンテナイメージで吸収できます。

最新安定版はv4.1系（v4.1.5が2026年10月9日公開）で、v4.0系も同日にv4.0.13が出ており2系統が保守されています。v4.0ではPython SDKがリポジトリから外れ、CronWorkflowの単数形 schedule が削除されました。古い記事のYAMLをそのまま貼ると動かない点に注意が要ります。

採用の目安ははっきりしています。すでにKubernetesを運用していて、バッチ処理・機械学習の学習ジョブ・CIの重い処理をコンテナ単位で並列に回したいなら有力です。Kubernetesを持っていないチームが、ワークフローのためだけにクラスターを立てるのは過剰投資になります。常駐アプリの配信はArgo CD、終わりのあるジョブはArgo Workflows、と分けると構成がぶれません。

Argo Workflowsの仕組み：Pod単位で動くCRDベースのワークフローエンジン

まず全体像です。Argo Workflowsをクラスターに入れると、Workflow・WorkflowTemplate・CronWorkflow などのCRDが追加され、ワークフローコントローラーがそれらを監視してPodを順に起動します。前提となるKubernetesの基本はKubernetes（クバネティス）とは？メリット・デメリットと仕組みで整理しています。

ステップがPodになる構造とstepsとDAGの2つの書き方

Workflowの中身は templates の配列で、1つ1つの template が「何を実行するか」を表します。実行単位になるのは container や script の template で、これらがPodとして起動します。

組み立て方は、stepsとDAGの2種類です。steps は「1段目が終わったら2段目」と段を積む書き方で、同じ段に並べたステップは並列に走る構造です。dag は各タスクに依存先を書き、依存の無いタスクから即座に実行されます。分岐と合流が多い処理ならDAGのほうが読みやすく、本記事の例もDAGで書きます。

Pod単位であることには代償もあります。1ステップごとにPodのスケジューリングとイメージ取得が挟まるため、数秒で終わる小さな処理を何百段もつなぐ用途には向きません。

WorkflowとWorkflowTemplateの違いとtemplateの意味

名前が似ていて混乱しやすいところです。公式のWorkflow Templatesのドキュメントは、小文字の template を「Workflow内のタスク」、WorkflowTemplate を「クラスター内に置いておくWorkflowの定義」と区別しています。

実務での使い分けは単純です。Workflow は実行1回ぶんの記録で、流すたびに増えます。WorkflowTemplate は再利用する定義で、Gitで管理してクラスターへ配る対象です。ほかのWorkflowTemplateの template を部品として呼ぶ templateRef、WorkflowTemplate全体からWorkflowを起こす workflowTemplateRef の2つを覚えておけば、定義の共通化はほぼ書けます。

CNCF Graduatedのプロジェクト構成とv4.1系の保守状況

Argo WorkflowsはArgo CD・Argo Rollouts・Argo Eventsと並ぶArgoプロジェクトの一部で、ArgoはCNCFのGraduatedプロジェクトに位置づけられています（2022年12月に到達）。

リリースはGitHub Releasesで追えます。2026年10月時点ではv4.1系とv4.0系のパッチが同じ日に出る運用で、直近ではv4.1.5とv4.0.13が10月9日に公開されました。新規導入ならv4.1系を選び、既存のv3系からはv4.0の破壊的変更を確認してから上げる、という順番が安全です。

検証環境にv4.1系を入れてhello-worldワークフローを流す手順

ここからは、検証環境で実際に動かす手順です。kindやminikube、Docker DesktopのKubernetesなど、手元のクラスターと kubectl があれば始められます。手順は公式のQuick Startに沿っています。

quick-start-minimal.yamlでargo名前空間へ入れるインストール

バージョンを変数に置き、argo 名前空間を作ってマニフェストを適用します。v4.1.5のリリースには quick-start-minimal.yaml が同梱されています。

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 get pods

公式手順はどちらも --server-side 付きの適用です。v4.0からはバリデーション情報まで含むFull CRDが既定になり、kubectl explain でフィールドの説明を引けるようになりました。quick-startのマニフェストは検証用の設定なので、本番環境は公式のインストールガイドに沿って install.yaml や namespace-install.yaml から組み直します。

argo CLIとUIのport-forwardでhello-worldの実行確認

Podが Running になったら、公式サンプルを投げて動作を確かめます。--watch を付けると進行状況と成否がそのまま表示されます。

argo submit -n argo --watch https://raw.githubusercontent.com/argoproj/argo-workflows/main/examples/hello-world.yaml
argo list -n argo

# UIを開く場合
kubectl -n argo port-forward service/argo-server 2746:2746

UIは http ではなく https://localhost:2746 で開きます。自己署名証明書なのでブラウザの警告を手動で承認する必要があります。Helmチャートで入れた場合はService名が argo-workflows-server に変わるので、port-forwardの対象もそちらに読み替えてください。

WorkflowTemplateとDAGで依存関係つきのジョブを定義して流す方法

hello-worldが通ったら、実務に近い形に進みます。例として「抽出→2系統の変換を並列→ロード」というデータ処理をDAGで組み、WorkflowTemplateとして登録します。

抽出から並列変換とロードまでをDAGで組むWorkflowTemplateの例

依存関係は dependencies の配列で書きます。transform-a と transform-b はどちらも extract だけに依存しているので並列に走り、load は両方の完了を待ちます。公式のDAGのウォークスルーにあるダイヤモンド型と同じ形です。

apiVersion: argoproj.io/v1alpha1
kind: WorkflowTemplate
metadata:
  name: etl-diamond
  namespace: argo
spec:
  entrypoint: main
  arguments:
    parameters:
      - name: target-date
        value: "2026-10-01"
  templates:
    - name: main
      dag:
        tasks:
          - name: extract
            template: step
            arguments:
              parameters:
                - name: msg
                  value: "extract {{workflow.parameters.target-date}}"
          - name: transform-a
            dependencies: [extract]
            template: step
            arguments:
              parameters:
                - name: msg
                  value: "transform-a"
          - name: transform-b
            dependencies: [extract]
            template: step
            arguments:
              parameters:
                - name: msg
                  value: "transform-b"
          - name: load
            dependencies: [transform-a, transform-b]
            template: step
            arguments:
              parameters:
                - name: msg
                  value: "load"
    - name: step
      inputs:
        parameters:
          - name: msg
      retryStrategy:
        limit: "2"
        retryPolicy: "OnFailure"
      container:
        image: busybox:1.36
        command: [sh, -c]
        args: ["echo {{inputs.parameters.msg}}"]

実行部品の step を1つだけ定義し、4つのタスクから引数違いで呼んでいる点がこの例の肝です。実際の処理に差し替えるときは、image と args を自社のコンテナに変えるだけで骨格は残せます。

argo template createとargo submit –fromの役割分担

定義の登録と実行を別コマンドに分けておくと、同じ定義を日付違いで何度でも流せます。-p で渡した値は arguments の既定値を上書きします。

argo template create etl-diamond.yaml -n argo
argo submit -n argo --from workflowtemplate/etl-diamond -p target-date=2026-10-15 --watch

この形にしておくと、WorkflowTemplateのYAMLをGitに置いてArgo CDで同期し、実行はCLIやCronWorkflowから起こす、という分業がそのまま組めます。Git側の運用設計はGitOpsとは：4原則とPush型との違い、Argo CD・Fluxの最小構成YAMLで扱っています。

fail fastの既定動作とfailFast falseで全ブランチを完走させる条件

DAGは既定で fail fast です。1つのタスクが失敗した時点で新しいタスクはスケジュールされず、実行中のものが終わるとDAG全体が失敗になります。

この既定はたいていの処理で正解です。例外は「各ブランチが独立していて、1つの失敗で他の結果まで捨てたくない」ケースで、たとえば取引先ごとのファイル取り込みを並列に回す処理がこれにあたります。その場合だけ dag の下に failFast: false を書き、全ブランチを完走させてから失敗分を個別に再実行します。

CronWorkflowで定期実行を組みリトライと失敗時の挙動を設計する

定義ができたら、次は毎日決まった時刻に流す設定です。公式のCron Workflowsのドキュメントでは、CronWorkflowは「Workflowにcron用のオプションを足したもの」と説明されています。

v4.0以降のschedules必須に合わせたCronWorkflowのYAML例

先ほどのWorkflowTemplateを毎日2時（日本時間）に流す例です。v4.0で単数形の schedule が削除されたため、schedules をリストで書きます。空のリストは受け付けられません。

apiVersion: argoproj.io/v1alpha1
kind: CronWorkflow
metadata:
  name: etl-nightly
  namespace: argo
spec:
  schedules:
    - "0 2 * * *"
  timezone: "Asia/Tokyo"
  concurrencyPolicy: "Forbid"
  startingDeadlineSeconds: 600
  successfulJobsHistoryLimit: 3
  failedJobsHistoryLimit: 1
  workflowSpec:
    workflowTemplateRef:
      name: etl-diamond

timezone を省くとコントローラーが動くマシンのタイムゾーンになるので、UTCで動くマネージドKubernetesでは9時間ずれます。明示しておくのが無難です。

concurrencyPolicyと履歴保持数の既定値と変えるべき場面

既定値と、変える判断の目安は次のとおりです。

concurrencyPolicy（既定 Allow）：前回が終わる前に次を流すと重複書き込みになる処理は Forbid にする。Replace は古い実行を消してから新しい実行を始める
startingDeadlineSeconds（既定 0）：コントローラーの停止中に逃した回を、指定秒数以内なら1回だけ拾う
successfulJobsHistoryLimit（既定 3）：成功履歴を長く見たいなら増やし、Podが溜まるなら減らす
failedJobsHistoryLimit（既定 1）：失敗の傾向を追いたいときに増やす

ETLのように同じテーブルへ書く処理は、Allow のままだと長引いた前日分と当日分が同時に走ります。夜間バッチは Forbid を起点に考え、取りこぼしを許せない処理だけ startingDeadlineSeconds を足す、という順で決めると迷いません。

retryStrategyのretryPolicy4種類と一時的な障害への備え方

先のYAMLでは実行部品に retryStrategy を付けました。公式のRetriesのドキュメントによると、retryPolicy は次の4種類で、既定は OnFailure です（expression を併用した場合は Always）。

OnFailure：メインコンテナが失敗したステップを再実行する
OnError：コントローラーのエラーやinit・waitコンテナの失敗を再実行する
OnTransientError：一時的なエラー、または TRANSIENT_ERROR_PATTERN 環境変数に一致するエラーだけを再実行する
Always：失敗の種類を問わず再実行する

外部APIを叩くステップなら OnFailure に backoff で待ち時間を足すのが基本形です。Always は設定ミスによる失敗まで回数ぶん繰り返すので、原因の切り分けが遅れます。冪等でない書き込み処理には付けないでください。

Argo CDとの役割分担とAirflow・Tektonとの使い分けの判断基準

最後に、どこまでをArgo Workflowsに任せ、どこから別の道具を選ぶかを言い切ります。

常駐アプリはArgo CD、終わりのあるジョブはArgo Workflowsに分ける

ArgoCDとは？GitOpsの仕組みとインストール・Sync設定で扱ったArgo CDは、クラスターの状態をGitの宣言に保ち続ける道具です。Deploymentのように動き続けるものを対象にしていて、「完了」という概念がありません。

Argo Workflowsは逆で、開始して終わるジョブを扱います。両方を使うときの分け方は、WorkflowTemplateやCronWorkflowの定義そのものをArgo CDでGitから同期し、実行と履歴はArgo Workflowsに任せる形です。実行記録の Workflow リソースは流すたびにクラスター上で生まれるものなので、Gitには置かず、Argo CDの同期対象にも含めません。

Airflow・Tekton・TemporalとArgo Workflowsの選定条件

近い道具との比較を、判断に効く軸だけで並べます。

道具	定義の書き方	向く用途	Kubernetes
Argo Workflows	YAML（CRD）	コンテナ単位のバッチ・ML・重いCI処理	必須
Apache Airflow	Python（DAG）	データパイプラインの定期実行	任意
Tekton	YAML（CRD）	ビルドとテストのCIパイプライン	必須
Temporal	アプリのコード	長時間かかる業務プロセス	任意

Argo Workflowsを選ぶのは、Kubernetesがすでにあり、ステップごとに言語やイメージが違う処理を並列に流したいときです。Pythonで書くデータエンジニアが中心で、センサーやバックフィルの機能を重く使うならApache Airflowが素直です。用途がビルドとテストに限られるならTekton、人の承認待ちを挟む数日がかりの業務処理ならTemporalのほうが設計が楽になります。

Kubernetes未導入のチームやPython SDK依存の構成は見送る

見送るべき場面も2つ挙げておきます。1つ目は、Kubernetesを運用していないチームです。ワークフローのためにクラスターの運用、アップグレード、監視まで抱えることになり、月数本のバッチならマネージドのワークフローサービスやcronのほうが総コストは低く収まります。

2つ目は、旧Python SDKでワークフローを組んでいる既存構成です。Upgrading Guideのとおりv4.0でリポジトリから削除され、更新もサポートも止まりました。移行先にはHeraが案内されているため、v4系へ上げる前にHeraへの書き換えを工数に積む必要があります。

Kubernetes上にワークフロー基盤を新しく組む場合や、既存のCI/CDとArgo CD・Argo Workflowsをつなぎ直す場合は、DevOps・CI/CD導入支援で設計から運用の引き継ぎまで相談を受けています。

よくある質問

Argo Workflowsの導入前によく出る疑問に、公式ドキュメントの記述をもとに答えます。

Argo WorkflowsとArgo CDは何が違うのですか？

Argo CDはGitに書いた宣言どおりにクラスターの状態を保ち続けるGitOpsの継続的デリバリーツールで、動き続けるアプリが対象です。Argo Workflowsは開始して完了するジョブを、コンテナの組み合わせとして順序どおりに実行するワークフローエンジンです。同じArgoプロジェクトの別製品で、併用する場合はWorkflowTemplateの定義をArgo CDで配り、実行をArgo Workflowsに任せます。

Argo Workflowsは無料で使えますか？

Argo Workflows自体はオープンソースで、ライセンス費用はかかりません。費用が出るのは、動かすKubernetesクラスターのノード代と、成果物を置くS3などのストレージ代です。ステップがPodとして動くので、並列数を増やすほどノードの台数が必要になります。CronWorkflowの履歴保持数を絞ってPodを溜めないことも、ノード費用を抑える手になります。

ステップ間でファイルを受け渡すには何が必要ですか？

小さな値を次のステップへ渡す方法は、出力パラメータです。ファイルを渡す場合はアーティファクトを使い、S3やGCSなどの保存先をアーティファクトリポジトリとして事前に設定することが必要です。設定方法は公式のConfiguring Your Artifact Repositoryにまとまっています。本番では保存先の認証情報をSecretで渡し、成果物の保持期間をストレージ側のライフサイクル設定で決めておきます。

v3系からv4系へ上げるときに何を確認すればよいですか？

確認の起点は、Upgrading Guideに記載された破壊的変更です。CronWorkflowの単数形 schedule、Workflowの podPriority・単数形の mutex と semaphore はv4.0で削除されたので、手元のYAMLを検索して該当箇所を置き換える必要があります。旧Python SDKを使っている場合は、Heraへの移行も必要です。CRDの適用は --server-side で行います。v4.1ではargo archiveコマンドが名前でも指定できるようになりました。

Kubernetesの知識はどの程度必要ですか？

Pod・Namespace・ServiceAccountとRBACの意味が分かり、kubectl でログや状態を追えれば、検証環境で動かすところまでは進められます。本番運用ではこれに加えて、ステップのPodに付ける権限の絞り込み、リソース要求の設定、コントローラーの監視が必要です。ワークフローの失敗の多くはPodの起動失敗やイメージ取得失敗として現れるため、Kubernetes側の切り分けができる人を1人は置いておくべきです。