Kargo (Promotion Gate) 包括的技術ガイド

目次

1. はじめに
2. Kargo とは何か
3. GitOps とContinuous Promotion の違い
4. アーキテクチャ概要
5. コアコンセプト
6. Project
7. Warehouse
8. Freight
9. Stage
10. Promotion と Promotion Template
11. Promotion Task
12. Promotion Steps リファレンス
13. Verification（検証）
14. AnalysisTemplate
15. Promotion Gate（プロモーションゲート）
16. Soak Time（ソークタイム）
17. Auto-Promotion（自動プロモーション）
18. Expression Language
19. Argo CD 連携
20. パイプライン構成パターン
21. リポジトリ構成パターン
22. セキュリティとアクセス制御
23. インストールとセットアップ
24. 実践的な構成例
25. トラブルシューティングとFAQ
26. ロードマップと今後の展望
27. まとめ

---

1. はじめに

ソフトウェアデリバリーの世界において、コードを「ビルド」し「テスト」し「デプロイ」するプロセスは年々複雑化している。特に Kubernetes エコシステムにおいては、GitOps の原則に基づいた継続的デリバリーが広く採用されているが、複数の環境（ステージング、UAT、本番など）を横断してアーティファクトを安全かつ確実に昇格（Promote）させる仕組みは、依然として多くの組織にとって課題であった。

Kargo は、Akuity 社が開発したオープンソースのアプリケーションライフサイクルオーケストレーションプラットフォームである。GitOps の原則を基盤としながら、ソフトウェアアーティファクトのライフサイクル各段階を通じた「プロモーション（昇格）」を管理・自動化することに特化している。

本稿では、Kargo の全体像を包括的に解説する。特に「Promotion Gate（プロモーションゲート）」の概念を中心に、アーキテクチャ、コアコンセプト、設定例、パターン、セキュリティ、そして実践的な構成方法に至るまで、詳細に論じる。

---

2. Kargo とは何か

2.1 概要

Kargo は、「unopinionated continuous promotion platform（非固定的な継続的プロモーションプラットフォーム）」と自らを定義している。これは、開発者が新しいコードや設定をアプリケーションライフサイクルの各ステージを通じてオーケストレーションする際に、GitOps の原則を活用するプラットフォームである。

主な特徴は以下の通りである：

• GitOps ネイティブ: Git リポジトリを信頼の源泉（Source of Truth）として活用
• マルチステージパイプライン: 複数の環境を横断するプロモーションパイプラインを定義
• 宣言的構成: Kubernetes CRD（Custom Resource Definition）として全てのリソースを定義
• Argo CD との深い統合: GitOps エージェントとしての Argo CD と連携してデプロイメントを実行
• 柔軟なゲーティング: Verification、Soak Time、Manual Approval などによるプロモーション制御
• Apache 2.0 ライセンス: 完全なオープンソース

2.2 Kargo が解決する問題

従来の CI/CD パイプラインでは、以下のような課題が存在していた：

1. 環境間の一貫性の欠如: 各環境へのデプロイメントが独立しており、アーティファクトの組み合わせの整合性が保証されない
2. 手動プロセスの増大: ステージング → 本番への昇格が手動で行われ、エラーが発生しやすい
3. 監査証跡の不足: 何がいつどの環境にデプロイされたかの追跡が困難
4. ロールバックの複雑さ: 問題発生時のロールバックが複雑で時間がかかる
5. GitOps の限界: Argo CD のような GitOps ツールは「デプロイメント」に優れるが「プロモーション」の概念が欠落

Kargo はこれらの課題を、宣言的なプロモーションパイプラインの概念で解決する。

2.3 プロジェクトの成熟度

Kargo は活発に開発が進められているプロジェクトであり、以下の指標がその成熟度を示している：

• GitHub Star: 約3,200以上
• フォーク数: 350以上
• リリース数: 179以上（最新 v1.9.5）
• 主要言語: Go (65.4%)、TypeScript (32.7%)
• ライセンス: Apache 2.0

---

3. GitOps とContinuous Promotion の違い

3.1 Continuous Deployment vs Continuous Promotion

Kargo を理解する上で最も重要な概念の一つが、「Continuous Deployment（継続的デプロイメント）」と「Continuous Promotion（継続的プロモーション）」の明確な区別である。

**Continuous Deployment（継続的デプロイメント）**は、望ましい状態（Desired State）をクラスタの実際の状態に同期させるプロセスである。Argo CD のような GitOps エージェントがこの役割を担い、Git リポジトリに記述された状態をクラスタに適用する。

[Git Repository] → [Argo CD] → [Kubernetes Cluster]
  (Desired State)     (Sync)      (Actual State)

**Continuous Promotion（継続的プロモーション）**は、望ましい状態そのものを、ある環境から次の環境へ伝播させるプロセスである。Kargo はこの「プロモーション」に特化しており、アーティファクトや設定の変更を安全にパイプラインの上流から下流へ流していく。

[Warehouse] → [Stage: Test] → [Stage: UAT] → [Stage: Production]
  (Source)     (Promotion)     (Promotion)      (Promotion)

3.2 プロモーションの本質

プロモーションの本質は、「ある環境で検証されたアーティファクトの組み合わせを、次の環境に反映すること」である。具体的には以下の操作が含まれる：

1. Git リポジトリの設定ファイルの更新（image tag の変更など）
2. Helm values ファイルの更新
3. Kustomize overlay の変更
4. Argo CD Application のシンク操作のトリガー

これらの操作は全て Git を通じて行われるため、完全な監査証跡が Git の履歴として残される。Kargo の公式ドキュメントが強調するように、「Git becomes a full audit trail of every promotion（Git がすべてのプロモーションの完全な監査証跡となる）」のである。

---

4. アーキテクチャ概要

4.1 コアデータモデル

Kargo は Kubernetes コントローラとして動作し、以下のカスタムリソース（CRD）を管理する：

リソース	スコープ	説明
Project	Cluster	プロジェクトの定義。対応する Namespace を自動作成
ProjectConfig	Namespace	プロジェクトレベルの設定（プロモーションポリシーなど）
Warehouse	Namespace	アーティファクトソースの監視と Freight の生成
Freight	Namespace	アーティファクトのバージョン参照のコレクション
Stage	Namespace	プロモーションターゲットとなる環境の定義
Promotion	Namespace	Freight を Stage に昇格させる操作
PromotionTask	Namespace	再利用可能なプロモーションステップの集合
ClusterPromotionTask	Cluster	クラスタスコープの PromotionTask
AnalysisTemplate	Namespace	検証テストの定義（Argo Rollouts CRD）
ClusterAnalysisTemplate	Cluster	クラスタスコープの AnalysisTemplate
AnalysisRun	Namespace	検証テストの実行インスタンス

「Kargo コントロールプレーン」とは、これらのリソースとコアサービスをホストするクラスタのことを指す。

4.2 コンポーネント構成

インターネット向けコンポーネント

コンポーネント	説明
API Server	バックエンドサービスを提供し、SPA（シングルページアプリケーション）のUIをホスト
External Webhooks Server	GitHub 等の外部システムからのWebhookリクエストを受信

コントロールプレーン必須コンポーネント

コンポーネント	説明
Controller	リポジトリの監視とプロモーションの実行を担当。分散配置可能
Kubernetes Webhooks Server	Validating/Mutating Webhook を実装。「Kargo の適切な動作に不可欠」
Management Controller	パーミッション管理を担当。これも「省略不可」
Garbage Collector	古いデータを削除してパフォーマンスを維持

ユーザーインターフェース

インターフェース	説明
Web UI	ブラウザベースのダッシュボード
CLI	コマンドラインツール
kubectl	Kubernetes ネイティブな操作

オプションコンポーネント

コンポーネント	説明
Dex	OpenID Connect アダプタ。GitHub 等のIDプロバイダとの連携用

4.3 デプロイメントアーキテクチャ

Kargo は2つのデプロイメントモデルをサポートする。

スタンドアロンモード

単一クラスタ内にコントロールプレーンとターゲットアプリケーションの両方をデプロイするモデル。テストや小規模のデプロイメントに適している。

分散（エージェントベース）モード

複数のクラスタにコントローラを「シャード」として分散配置するモデル。各シャードは中央のコントロールプレーンに接続し、一元的な可観測性を確保しながらも、セキュリティと分散性を両立させる。

重要な設計上の利点として、コントロールプレーンは各クラスタへの特権アクセスを持たない点がある。これにより、従来のハブアンドスポークモデルの弱点（中央管理による単一障害点リスク）を回避しつつ、集中管理の利便性を享受できる。

---

5. コアコンセプト

Kargo のコアコンセプトは最小限の用語で構成されており、以下の5つの主要概念で全体が理解できる：

1. Warehouse（倉庫）: アーティファクトリポジトリを監視し、新しいバージョンを検出して Freight を生成
2. Freight（貨物）: コンテナイメージ、Kubernetes マニフェスト、Helm チャートなどのバージョン参照を束ねたメタアーティファクト
3. Stage（ステージ）: プロモーションのターゲットとなる環境。パイプラインのノード
4. Promotion（プロモーション）: Freight を Stage に組み込む操作
5. Project（プロジェクト）: 上記全てを組織的に管理する単位

これらが連鎖してパイプラインを形成し、アーティファクトの流れを制御する。

---

6. Project

6.1 概要

Project は Kargo のリソース管理の最上位単位であり、クラスタスコープの Kubernetes リソースとして定義される。Project を作成すると、対応する Namespace が自動的に生成され、必要なボイラープレート設定（RBAC、ServiceAccount など）も自動で構成される。

6.2 最小構成

apiVersion: kargo.akuity.io/v1alpha1
kind: Project
metadata:
  name: my-app

6.3 ProjectConfig とプロモーションポリシー

apiVersion: kargo.akuity.io/v1alpha1
kind: ProjectConfig
metadata:
  name: my-app
  namespace: my-app
spec:
  promotionPolicies:
    - stage: test
      autoPromotionEnabled: true
    - stage: uat
      autoPromotionEnabled: true
    - stage: production
      autoPromotionEnabled: false

高度なセレクタとして、正規表現（regex:）、Glob パターン（glob:）、Kubernetes ラベルセレクタもサポートされる。

---

7. Warehouse

7.1 概要

Warehouse はアーティファクトソースを監視し、新しいリビジョンが検出されると Freight リソースを生成する。

7.2 サブスクリプションタイプ

コンテナイメージサブスクリプション

apiVersion: kargo.akuity.io/v1alpha1
kind: Warehouse
metadata:
  name: my-warehouse
  namespace: my-app
spec:
  subscriptions:
    - image:
        repoURL: public.ecr.aws/nginx/nginx
        imageSelectionStrategy: SemVer
        semverConstraint: ^1.0.0
        allowTagsRegexes:
          - ^v?\d+\.\d+\.\d+$
        platform: linux/amd64
        discoveryLimit: 20

イメージ選択戦略: SemVer（デフォルト）、Lexical、Digest、NewestBuild

Git リポジトリサブスクリプション

spec:
  subscriptions:
    - git:
        repoURL: https://github.com/example/repo.git
        commitSelectionStrategy: NewestFromBranch
        branch: main
        includePaths:
          - config/**
        excludePaths:
          - config/test/**

コミット選択戦略: NewestFromBranch（デフォルト）、SemVer、Lexical、NewestTag

Helm チャートサブスクリプション

spec:
  subscriptions:
    - chart:
        repoURL: https://charts.example.com
        name: my-chart
        semverConstraint: ^2.0.0
        discoveryLimit: 20

7.3 高度な機能

• Freight 生成制御: freightCreationPolicy: Manual で手動制御、freightCreationCriteria で式ベースの条件定義
• Webhook レシーバー: GitHub、GitLab、Gitea からのイベントで検出をトリガー
• パフォーマンス最適化: spec.interval、cacheByTag、allowTagsRegexes による調整

---

8. Freight

8.1 概要

Freight は Kargo における中心的なメタアーティファクトであり、コンテナイメージ、Kubernetes マニフェスト、Helm チャートなどのバージョン参照を一つの単位として束ねたものである。

8.2 名前と識別

Freight リソースの名前は、含まれるアーティファクト参照から決定論的に計算された SHA-1 ハッシュを使用する。

8.3 エイリアス

Warehouse は Freight に対して、「形容詞-動物」形式のエイリアスを自動生成する（例：happy-dolphin）。ユーザーはカスタムエイリアスで上書きすることも可能。

8.4 手動承認（Manual Approval）

kargo approve --project my-app --freight <freight-id> --stage production

手動承認は、Verification 要件と Soak Time 要件の両方をバイパスする。

8.5 OCI イメージアノテーション

Kargo は org.opencontainers.image.source と org.opencontainers.image.revision を認識し、UI でリンクを自動生成する。

---

9. Stage

9.1 概要

Stage はプロモーションのターゲットとなる環境を表す Kubernetes リソースである。Stage の spec は4つの主要セクションで構成される。

9.2 Variables（変数）

spec:
  vars:
    - name: gitRepo
      value: https://github.com/example/config.git
    - name: targetBranch
      value: ${{ ctx.stage }}

9.3 Requested Freight（要求 Freight）

spec:
  requestedFreight:
    - origin:
        kind: Warehouse
        name: my-warehouse
      sources:
        direct: true
    - origin:
        kind: Warehouse
        name: my-warehouse
      sources:
        stages:
          - test
          - uat
        availabilityStrategy: OneOf

• Direct: Warehouse が生成した Freight が即座に利用可能
• Upstream: 上流 Stage で Verified された Freight のみ利用可能
• Availability Strategy: OneOf（デフォルト）または All

9.4 Promotion Template（プロモーションテンプレート）

spec:
  promotionTemplate:
    spec:
      steps:
        - uses: git-clone
          config:
            repoURL: ${{ vars.gitRepo }}
            checkout:
              - branch: main
                path: ./src
        - uses: kustomize-set-image
          config:
            images:
              - image: public.ecr.aws/nginx/nginx
                path: ./src/environments/${{ ctx.stage }}
        - uses: git-commit
          config:
            path: ./src
            messageExpression: |
              "Promote image to ${{ ctx.stage }}"
        - uses: git-push
          config:
            path: ./src
        - uses: argocd-update
          config:
            apps:
              - name: my-app-${{ ctx.stage }}
                sources:
                  - repoURL: ${{ vars.gitRepo }}

9.5 Verification（検証）

spec:
  verification:
    analysisTemplates:
      - name: integration-tests
      - name: smoke-tests

---

10. Promotion と Promotion Template

10.1 変数スコープ

• グローバル変数: spec.vars に定義、${{ vars.変数名 }} で参照
• ステップ変数: ${{ outputs.stepAlias.outputName }} で参照

10.2 条件付き実行

steps:
  - uses: argocd-update
    if: ${{ success() }}
    config:
      apps:
        - name: my-app
  - uses: send-message
    if: ${{ failure() }}
    config:
      message: "Promotion failed for ${{ ctx.stage }}"
  - uses: set-metadata
    if: ${{ always() }}
    config:
      metadata:
        completedAt: ${{ now() }}

10.3 エラーハンドリング

steps:
  - uses: http
    config:
      url: https://api.example.com/notify
    continueOnError: true
  - uses: argocd-update
    retry:
      errorThreshold: 3
      timeout: 5m
    config:
      apps:
        - name: my-app

---

11. Promotion Task

11.1 概要

Promotion Task は再利用可能なプロモーションステップの集合。PromotionTask（プロジェクトスコープ）と ClusterPromotionTask（クラスタスコープ）の2種類が存在する。

11.2 定義例

apiVersion: kargo.akuity.io/v1alpha1
kind: PromotionTask
metadata:
  name: deploy-with-kustomize
  namespace: my-app
spec:
  vars:
    - name: repoURL
    - name: targetPath
      value: ./environments
    - name: imageRepo
  steps:
    - uses: git-clone
      as: clone
      config:
        repoURL: ${{ vars.repoURL }}
        checkout:
          - branch: main
            path: ./src
    - uses: kustomize-set-image
      config:
        images:
          - image: ${{ vars.imageRepo }}
            path: ${{ vars.targetPath }}/${{ ctx.stage }}
    - uses: git-commit
      config:
        path: ./src
        messageExpression: |
          "Promote to ${{ ctx.stage }}"
    - uses: git-push
      config:
        path: ./src
    - uses: compose-output
      config:
        commitSHA: ${{ task.outputs['clone'].commit }}

11.3 テンプレートからの参照

spec:
  promotionTemplate:
    spec:
      steps:
        - task:
            name: deploy-with-kustomize
          config:
            repoURL: https://github.com/example/config.git
            imageRepo: public.ecr.aws/nginx/nginx

制約: Task は他の Task を参照できない（循環依存防止）。

---

12. Promotion Steps リファレンス

Kargo は49種類以上の組み込みプロモーションステップを提供している。

Git 操作

git-clone, git-commit, git-push, git-tag, git-clear, git-open-pr, git-wait-for-pr, git-merge-pr

Argo CD 統合

argocd-update, argocd-wait

設定ファイル操作

yaml-update, yaml-parse, yaml-merge, json-update, json-parse, toml-update, toml-parse, hcl-update

Kubernetes/コンテナ

kustomize-build, kustomize-set-image, helm-template, helm-update-chart, oci-download, oci-push

Terraform

tf-plan, tf-apply, tf-output

GitHub Actions

gha-dispatch-workflow, gha-wait-for-workflow

インテグレーション

jira, jfrog-evidence, snow-create, snow-update, snow-delete, snow-query-for-records, snow-wait-for-condition

HTTP/ファイル操作

http, http-download, copy, delete, untar

メタデータ/制御

compose-output, set-metadata, set-freight-alias, send-message, fail

---

13. Verification（検証）

13.1 概要

Verification は、プロモーション後に Freight がその Stage で正常に動作しているかを確認するためのオプション機能である。

最も重要なルール: 上流 Stage に Verification が設定されている場合、Freight はその Stage で検証に合格するまで、下流の Stage へのプロモーション資格を得ることができない。これが Kargo の「Promotion Gate」の核心的な仕組みである。

13.2 Verification ワークフロー

1. Promotion 実行 → Stage Phase: "Progressing"
2. Promotion 成功 → Stage Phase: "Verifying"
3. AnalysisTemplate に基づき AnalysisRun を生成 → AnalysisRun Phase: "Running"
4. 検証成功 → Freight Status: "Verified"、下流 Stage へのプロモーション資格獲得
5. 検証失敗 → Freight は "Verified" にならず、下流へのプロモーション不可

検証中は、その Stage への他のプロモーションは実行不可。

13.3 設定例

apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
metadata:
  name: test
  namespace: my-app
spec:
  requestedFreight:
    - origin:
        kind: Warehouse
        name: my-warehouse
      sources:
        direct: true
  promotionTemplate:
    spec:
      steps:
        - uses: git-clone
          config:
            repoURL: https://github.com/example/config.git
            checkout:
              - branch: main
                path: ./src
  verification:
    analysisTemplates:
      - name: integration-tests
      - name: smoke-tests
    args:
      - name: stage-name
        value: ${{ ctx.stage }}
    analysisRunMetadata:
      labels:
        app: my-app

13.4 暗黙的な Argo CD 検証

Stage が Argo CD と統合されているが明示的な Verification が設定されていない場合、検証は暗黙的に Argo CD Application が Healthy 状態に到達することに依存する。

---

14. AnalysisTemplate

14.1 概要

AnalysisTemplate は Argo Rollouts プロジェクトから借用した CRD であり、検証テストの具体的な実行方法を定義する。サポートするモニタリングシステム: Prometheus, Datadog, CloudWatch, NewRelic, InfluxDB, SkyWalking, Graphite。

14.2 Prometheus を使った例

apiVersion: argoproj.io/v1alpha1
kind: AnalysisTemplate
metadata:
  name: success-rate-check
  namespace: my-app
spec:
  args:
    - name: stage-name
    - name: threshold
      value: "0.95"
  metrics:
    - name: success-rate
      interval: 3m
      count: 20
      failureLimit: 3
      initialDelay: 2m
      provider:
        prometheus:
          address: http://prometheus:9090
          query: |
            sum(rate(
              http_requests_total{
                status=~"2..",
                namespace="{{ args.stage-name }}"
              }[5m]
            )) /
            sum(rate(
              http_requests_total{
                namespace="{{ args.stage-name }}"
              }[5m]
            ))
      successCondition: "result[0] >= {{ args.threshold }}"
      failureCondition: "result[0] < 0.80"

14.3 Kubernetes Job を使った例

apiVersion: argoproj.io/v1alpha1
kind: AnalysisTemplate
metadata:
  name: integration-tests
  namespace: my-app
spec:
  args:
    - name: stage-name
  metrics:
    - name: integration-test
      provider:
        job:
          spec:
            template:
              spec:
                containers:
                  - name: test-runner
                    image: my-tests:latest
                    env:
                      - name: TARGET_NAMESPACE
                        value: "{{ args.stage-name }}"
                    command:
                      - /bin/sh
                      - -c
                      - |
                        npm run test:integration
                restartPolicy: Never
            backoffLimit: 0

重要: AnalysisTemplate の引数は {{ args.<名前> }} 構文を使用する（Kargo の式言語 ${{ }} とは異なる）。

---

15. Promotion Gate（プロモーションゲート）

15.1 概念

Promotion Gate は、Kargo において Freight のパイプライン進行を制御する仕組みの総称である。単一のリソースではなく、複数のメカニズムの組み合わせで実現される：

• Verification Gate: AnalysisRun による検証
• Soak Time: 滞留時間要件
• Freight Availability Strategy: OneOf / All
• Manual Approval: 手動承認
• Auto-Promotion Policy: 自動プロモーションポリシー
• Implicit Argo CD Health Check: 暗黙のヘルスチェック

15.2 Verification Gate

最も一般的な Promotion Gate。上流 Stage で AnalysisTemplate に基づく検証が成功しない限り、Freight は下流への移動が許可されない。

15.3 Availability Strategy Gate

OneOf 戦略

spec:
  requestedFreight:
    - origin:
        kind: Warehouse
        name: my-warehouse
      sources:
        stages:
          - test-us
          - test-eu
        availabilityStrategy: OneOf

指定された上流 Stage の少なくとも1つで Freight が Verified であれば、下流へのプロモーションが可能。

All 戦略

spec:
  requestedFreight:
    - origin:
        kind: Warehouse
        name: my-warehouse
      sources:
        stages:
          - test-us
          - test-eu
          - test-asia
        availabilityStrategy: All

指定された全ての上流 Stage で Freight が Verified でなければならない。

15.4 Manual Approval Gate

手動承認は全ての Promotion Gate をバイパスする最後の手段：

kargo approve --project my-app --freight happy-dolphin --stage production

バイパスされるもの: Verification要件、Soak Time要件、Availability Strategy要件

15.5 Gatekeeper Stage パターン

意図的な「失敗ゾーン」として機能し、互換性のないアーティファクトの組み合わせを本番前に識別する Stage。

apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
metadata:
  name: compatibility-check
  namespace: my-app
spec:
  requestedFreight:
    - origin:
        kind: Warehouse
        name: frontend-warehouse
      sources:
        direct: true
    - origin:
        kind: Warehouse
        name: backend-warehouse
      sources:
        direct: true
  verification:
    analysisTemplates:
      - name: compatibility-matrix-test

15.6 Control Flow Stage パターン

Promotion Process を持たない Stage を定義し、承認ゲートとして使用する。

---

16. Soak Time（ソークタイム）

16.1 概念

Soak Time は、Freight が上流 Stage で一定時間「浸漬（soak）」してから下流の Stage へのプロモーション資格を得るという要件。時間経過とともに顕在化するメモリリークやパフォーマンス劣化などを発見するための期間。

16.2 設定方法

spec:
  requestedFreight:
    - origin:
        kind: Warehouse
        name: my-warehouse
      sources:
        stages:
          - test
        soakTime: 2h

単位: 30s（秒）、30m（分）、2h（時間）

Soak Time は Verification の完了後から計測される。手動承認で Soak Time 要件もバイパス可能。

---

17. Auto-Promotion（自動プロモーション）

17.1 設定

apiVersion: kargo.akuity.io/v1alpha1
kind: ProjectConfig
metadata:
  name: my-app
  namespace: my-app
spec:
  promotionPolicies:
    - stage: test
      autoPromotionEnabled: true
    - stage: uat
      autoPromotionEnabled: true
      autoPromotionOptions:
        selectionPolicy: NewestFreight
    - stage: production
      autoPromotionEnabled: false

17.2 Selection Policy

ポリシー	説明
NewestFreight	最新の適格な Freight を継続的にプロモーション
MatchUpstream	単一の上流 Stage で現在使用されている Freight をプロモーション

17.3 Promotion Gate と Auto-Promotion の連携

Warehouse → [Test: Auto+Verify] → [UAT: Auto+Verify+Soak] → [Prod: Manual]

---

18. Expression Language

18.1 概要

Kargo は expr-lang をベースとした式言語をサポート。式は ${{ }} デリミタで囲む。

18.2 主な組み込み関数

# アーティファクト情報
imageTag: ${{ imageFrom("public.ecr.aws/nginx/nginx").tag }}
commitSHA: ${{ commitFrom("https://github.com/example/config.git").id }}
chartVersion: ${{ chartFrom("https://charts.example.com", "my-chart").version }}

# Kubernetes リソース
dbHost: ${{ configMap("app-config").data.DB_HOST }}
dbPassword: ${{ secret("app-secrets").data.DB_PASSWORD }}

# セマンティックバージョニング
majorVersion: ${{ semverParse(imageFrom("nginx").tag).Major() }}

# 制御フロー
if: ${{ success() }}
if: ${{ failure() }}
if: ${{ always() }}

18.3 コンテキスト変数

変数	説明
ctx.project	プロジェクト名
ctx.stage	Stage 名
ctx.promotion	Promotion 名
ctx.freight	対象 Freight
ctx.actor	操作実行者
outputs	前のステップの出力結果
vars	ユーザー定義変数マップ
task	同一 PromotionTask 内の前のステップ出力

---

19. Argo CD 連携

19.1 Authorization（認可）

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app-test
  namespace: argocd
  annotations:
    kargo.akuity.io/authorized-stage: my-project:test

19.2 argocd-update ステップ

spec:
  promotionTemplate:
    spec:
      steps:
        - uses: argocd-update
          config:
            apps:
              - name: my-app-${{ ctx.stage }}
                sources:
                  - repoURL: https://github.com/example/config.git
                    desiredCommitFromStep: push

19.3 ヘルスモニタリング

Stage のヘルスステータスは、Promotion の成功/失敗、Argo CD Application のヘルス、Verification の結果など複数の要素を反映する。

---

20. パイプライン構成パターン

20.1 Image Updater パターン

単一の Warehouse がイメージリポジトリを監視し、複数の Stage を通じてイメージを昇格。

20.2 Config Updater パターン

Git リポジトリの設定変更を監視し、段階的にロールアウト。

20.3 Common Case パターン

イメージと設定の両方を単一の Warehouse で監視。

20.4 Parallel Pipelines パターン

単一プロジェクト内に複数の独立した DAG パイプラインを共存。

20.5 Fan-Out / Fan-In パターン

Freight を複数の並列 Stage に分散（Fan-Out）し、収束（Fan-In）させる。

20.6 Grouped Services パターン

関連サービスを単一の Freight にパッケージし、一緒にプロモーション。

20.7 Ordered Services パターン

関連サービスを特定の順序でプロモーション。

20.8 Multiple Warehouses パターン

異なるアーティファクトタイプに対して個別の Warehouse を設定。

20.9 Mixed Promotion Modes パターン

初期 Stage では自動、本番では手動プロモーション。

---

21. リポジトリ構成パターン

21.1 Helm レイアウト

基本設定の values.yaml と Stage 固有の環境ディレクトリ。

21.2 Kustomize レイアウト

共通 base と Stage 固有の overlays。

21.3 Monorepo レイアウト

アプリケーション名、Stage ごとにディレクトリを分離。

21.4 ストレージオプション

1. Stage 固有ブランチ（推奨）
2. メインブランチ内の分離ディレクトリ
3. 別リポジトリ

21.5 Rendered Configs パターン

helm template や kustomize build でレンダリングされたプレーン YAML を保存することを推奨。

---

22. セキュリティとアクセス制御

• RBAC: Kubernetes 標準の RBAC を活用。Project 作成時に基本 RBAC リソース自動生成
• API トークン: CI/CD システムからのプログラマティックアクセス
• シークレット管理: Kubernetes Secret による認証情報管理
• Argo CD Application の認可: 明示的なアノテーションによる認可
• SSO 連携: OIDC 準拠 IdP（Okta、Auth0、Microsoft Entra ID）+ Dex

---

23. インストールとセットアップ

23.1 前提条件

要件	バージョン
Helm	v3.13.1 以上
Kubernetes クラスタ	v1.29.3 以上（推奨）
cert-manager	v1.16.1 以上（必須）
Argo CD	v2.13.0 以上（推奨）
Argo Rollouts	v1.7.2 以上（推奨）

23.2 基本インストール

password="admin"
hashed_pass=$(htpasswd -bnBC 10 "" "${password}" | tr -d ':\n')
signing_key=$(openssl rand -base64 32)

helm install kargo \
  oci://ghcr.io/akuity/kargo-charts/kargo \
  --namespace kargo \
  --create-namespace \
  --set api.adminAccount.passwordHash="${hashed_pass}" \
  --set api.adminAccount.tokenSigningKey="${signing_key}" \
  --wait

重要: デフォルト設定はローカル開発環境でのテスト用途のみに適している。

---

24. 実践的な構成例

24.1 例1: 基本的な3ステージパイプライン

# Warehouse
apiVersion: kargo.akuity.io/v1alpha1
kind: Warehouse
metadata:
  name: my-app-warehouse
  namespace: my-app
spec:
  subscriptions:
    - image:
        repoURL: public.ecr.aws/nginx/nginx
        imageSelectionStrategy: SemVer
        semverConstraint: ^1.0.0
---
# Stage: Test (Direct from Warehouse, Auto-Promote, Verification)
apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
metadata:
  name: test
  namespace: my-app
spec:
  requestedFreight:
    - origin:
        kind: Warehouse
        name: my-app-warehouse
      sources:
        direct: true
  promotionTemplate:
    spec:
      steps:
        - task:
            name: kustomize-promote
          config:
            repoURL: https://github.com/example/config.git
  verification:
    analysisTemplates:
      - name: smoke-tests
---
# Stage: UAT (Upstream from Test, Auto-Promote, Verification)
apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
metadata:
  name: uat
  namespace: my-app
spec:
  requestedFreight:
    - origin:
        kind: Warehouse
        name: my-app-warehouse
      sources:
        stages:
          - test
  promotionTemplate:
    spec:
      steps:
        - task:
            name: kustomize-promote
          config:
            repoURL: https://github.com/example/config.git
  verification:
    analysisTemplates:
      - name: integration-tests
      - name: performance-tests
---
# Stage: Production (Upstream from UAT + Soak Time, Manual Only)
apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
metadata:
  name: production
  namespace: my-app
spec:
  requestedFreight:
    - origin:
        kind: Warehouse
        name: my-app-warehouse
      sources:
        stages:
          - uat
        soakTime: 4h
  promotionTemplate:
    spec:
      steps:
        - task:
            name: kustomize-promote
          config:
            repoURL: https://github.com/example/config.git
  verification:
    analysisTemplates:
      - name: production-health-check
---
# ProjectConfig (Auto-Promotion Settings)
apiVersion: kargo.akuity.io/v1alpha1
kind: ProjectConfig
metadata:
  name: my-app
  namespace: my-app
spec:
  promotionPolicies:
    - stage: test
      autoPromotionEnabled: true
    - stage: uat
      autoPromotionEnabled: true
    - stage: production
      autoPromotionEnabled: false

24.2 例2: マルチリージョン Fan-Out パイプライン

# Stage: Global Production (All regions must verify + Soak Time)
apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
metadata:
  name: global-production
  namespace: global-app
spec:
  requestedFreight:
    - origin:
        kind: Warehouse
        name: global-warehouse
      sources:
        stages:
          - us-west
          - eu-central
        availabilityStrategy: All
        soakTime: 6h

24.3 例3: ServiceNow 連携プロモーション

spec:
  promotionTemplate:
    spec:
      steps:
        - uses: snow-create
          as: change-request
          config:
            instanceURL: https://example.service-now.com
            table: change_request
            record:
              short_description: |
                Deploy ${{ imageFrom("my-app").tag }} to production
              category: Software
              priority: "3"
        - uses: git-clone
          as: clone
          config:
            repoURL: ${{ vars.repoURL }}
            checkout:
              - branch: main
                path: ./src
        - uses: argocd-update
          config:
            apps:
              - name: my-app-production
        - uses: snow-update
          if: ${{ success() }}
          config:
            instanceURL: https://example.service-now.com
            table: change_request
            sysId: ${{ outputs['change-request'].sysId }}
            record:
              state: "3"
              close_notes: "Deployment successful"
        - uses: snow-update
          if: ${{ failure() }}
          config:
            instanceURL: https://example.service-now.com
            table: change_request
            sysId: ${{ outputs['change-request'].sysId }}
            record:
              state: "4"
              close_notes: "Deployment failed"

---

25. トラブルシューティングとFAQ

25.1 よくある質問

• Q: Stage ごとに個別のブランチが必要？ A: いいえ。推奨オプションの一つだが必須ではない
• Q: モノレポをサポート？ A: はい。アプリケーション/サービスごとに設定を分離することを推奨
• Q: 複数マイクロサービスの一括プロモーション？ A: はい。Grouped Services / Ordered Services パターンで対応
• Q: 複数の Argo CD コントロールプレーン？ A: はい、サポートしている
• Q: SSO は？ A: OIDC 準拠 IdP + Dex をサポート

25.2 一般的なトラブルシューティング

• Freight が下流で利用不可: 上流の Verification 失敗、または Soak Time 未経過。kargo reverify で再検証、緊急時は kargo approve で手動承認
• Promotion が Pending: 別のプロモーションまたは検証が実行中。kargo refresh でリフレッシュ
• Argo CD が Healthy にならない: kargo.akuity.io/authorized-stage アノテーションを確認

---

26. ロードマップと今後の展望

• Promotion Steps の拡充: エンタープライズ統合ステップの追加
• マルチクラスタサポートの強化: 分散アーキテクチャの最適化
• UI/UX の改善: ダッシュボードの機能強化
• Akuity Enterprise: マネージドサービス、SLA、プロフェッショナルサポート
• コミュニティ: GitHub Issues/Discussions、Discord (akuity.community)

---

27. まとめ

27.1 Kargo の価値提案

1. Promotion Gate による安全な昇格: Verification、Soak Time、Manual Approval などの多層的なゲーティングメカニズム
2. GitOps ネイティブな設計: 完全な監査証跡が Git 履歴として自動保持
3. 宣言的パイプライン: Kubernetes CRD として定義、バージョン管理可能
4. 柔軟なアーキテクチャ: スタンドアロンから分散エージェントベースまで
5. 豊富な統合: 49以上の組み込みプロモーションステップ
6. 非固定的な設計思想: 既存のワークフローに適応

27.2 Promotion Gate のベストプラクティス

プラクティス	説明
段階的な検証	各 Stage に適切な AnalysisTemplate を設定し、段階的に厳格さを増す
Soak Time の活用	本番環境前に十分な Soak Time を設定
Auto-Promotion の適切な適用	初期 Stage は自動化、本番は手動承認
Availability Strategy の選択	マルチリージョンでは All 戦略
Manual Approval の制限	緊急時のみ使用
Gatekeeper Stage の活用	アーティファクト互換性を事前に検証

27.3 導入の指針

1. 評価フェーズ: Quickstart でローカル環境に基本パイプラインを構築
2. パイロットフェーズ: 非クリティカルなアプリで3ステージパイプライン構築
3. 拡大フェーズ: PromotionTask で標準化されたワークフローを組織展開
4. 最適化フェーズ: Soak Time、Fan-Out、ServiceNow 連携などの高度な機能を導入

---

本稿は 2026年4月時点の Kargo v1.9.x をベースに執筆されている。最新の情報は Kargo 公式ドキュメント および GitHub リポジトリ を参照されたい。