kargo-skill

Kargo スキル

Kargo の完全ガイドです。Kargo は、段階的デリバリー機能によって GitOps の原則を拡張する、特定の方式を強制しない継続的プロモーションプラットフォームです。

概要

Kargo は、環境間で望ましい状態をプロモートします。一方、ArgoCD などのツールは、Git 内の望ましい状態に実際の状態を同期します。Kargo はプロモーションロジックを担い、ArgoCD を補完します。

インストール

前提条件

• Helm v3.13.1 以降
• cert-manager が事前にインストールされた Kubernetes クラスター
• オプション：ArgoCD v2.13.0 以降、Argo Rollouts v1.7.2 以降

基本的なインストール（Helm）

# Generate required values
export ADMIN_PASSWORD_HASH=$(htpasswd -bnBC 10 admin <password> | cut -d: -f2)
export TOKEN_SIGNING_KEY=$(openssl rand -base64 48)

# Install Kargo
helm install kargo \
  oci://ghcr.io/akuity/kargo-charts/kargo \
  --namespace kargo \
  --create-namespace \
  --set api.adminAccount.passwordHash="$ADMIN_PASSWORD_HASH" \
  --set api.adminAccount.tokenSigningKey="$TOKEN_SIGNING_KEY" \
  --wait

クイックスタート（オールインワン）

curl -L https://raw.githubusercontent.com/akuity/kargo/main/hack/quickstart/install.sh | sh

トラブルシューティング

• 401 エラー：Helm を v3.13.1 以降に更新してください
• 403 エラー：docker logout ghcr.io を実行してください

主な概念

プロジェクト

プロモーションパイプラインを整理するためのテナント単位です。各プロジェクトは Kubernetes の名前空間に対応します。

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

ウェアハウス

リポジトリを監視して、新しいアーティファクトリビジョンを検出し、Freight にまとめます。

apiVersion: kargo.akuity.io/v1alpha1
kind: Warehouse
metadata:
  name: my-warehouse
  namespace: my-project
spec:
  subscriptions:
  - image:
      repoURL: public.ecr.aws/nginx/nginx
      imageSelectionStrategy: SemVer
      constraint: ^1.26.0
  - git:
      repoURL: https://github.com/example/repo.git
      branch: main
      commitSelectionStrategy: NewestFromBranch
  - chart:
      repoURL: https://charts.example.com
      name: my-chart
      semverConstraint: ^1.0.0

イメージ選択戦略

戦略	説明
SemVer（デフォルト）	セマンティックバージョニングの制約
Lexical	日付付きタグ向け（例：nightly-20231225）
Digest	latest などの可変タグを追跡
NewestBuild	イメージのメタデータを使用（パフォーマンス負荷が高い）

Git コミット選択戦略

戦略	説明
NewestFromBranch（デフォルト）	ブランチの最新コミット
SemVer	制約付きのタグ付きリリース
Lexical	辞書順で最大のタグ
NewestTag	最も最近作成されたタグ

Git 式フィルター

# Exclude bot commits
expressionFilter: !(author contains '<[email protected]>')

# Filter by commit message
expressionFilter: subject contains 'feat:' || subject contains 'fix:'

# Filter by date
expressionFilter: creatorDate.Year() >= 2024

パスフィルタリング

includePaths:
  - apps/guestbook
  - glob:apps/*/config
excludePaths:
  - apps/guestbook/README.md
  - regex:.*\.test\.yaml$

Freight

特定のアーティファクトリビジョンへの参照を含むメタアーティファクトです。関連するアーティファクトがパイプライン内を一緒に移動することを保証します。

# Update freight alias
kargo update freight \
  --project my-project \
  --name <freight-hash> \
  --new-alias frozen-tauntaun

# Manual approval
kargo approve \
  --project my-project \
  --freight <freight-id> \
  --stage prod

ステージ

相互に接続してパイプラインを形成するプロモーション先です。

apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
metadata:
  name: test
  namespace: my-project
spec:
  vars:
    - name: gitopsRepo
      value: https://github.com/example/repo.git
    - name: targetBranch
      value: stage/test

  requestedFreight:
    - origin:
        kind: Warehouse
        name: my-warehouse
      sources:
        direct: true

  promotionTemplate:
    spec:
      steps:
        - uses: git-clone
        - uses: kustomize-set-image
        - uses: git-commit
        - uses: git-push
        - uses: argocd-update

  verification:
    analysisTemplates:
      - name: integration-test

Freight の利用可能性戦略

• OneOf（デフォルト）：少なくとも 1 つの上流ステージで検証が必要です
• All：すべての上流ステージで検証が必要です

自動プロモーションポリシー

• NewestFreight：検証済みまたは承認済みの最新の Freight を継続的にプロモートします
• MatchUpstream：上流ステージの現在のバージョンに一致する Freight をプロモートします

プロモーション

GitOps を使用して、アプリケーションのライフサイクルの各ステージを通じてコードと設定の変更を移動します。

# Promote via CLI
kargo promote \
  --project my-project \
  --freight <freight-id> \
  --stage prod

# Using alias
kargo promote \
  --project my-project \
  --freight-alias frozen-tauntaun \
  --stage prod

プロモーションステップのリファレンス

Git 操作

git-clone

- uses: git-clone
  config:
    repoURL: https://github.com/example/repo.git
    author:
      name: "Kargo Bot"
      email: "[email protected]"
    checkout:
      - branch: main
        path: ./out
      - commit: abc123def456
        path: ./config
        create: true  # Create orphaned branch if missing

git-commit

- uses: git-commit
  as: commit
  config:
    path: ./out
    message: |
      Update image to ${{ imageFrom(vars.imageRepo).Tag }}
    author:
      name: "Kargo Automation"
      email: "[email protected]"

git-push

- uses: git-push
  as: push
  config:
    path: ./out
    targetBranch: ${{ vars.targetBranch }}
    maxAttempts: 50
    # OR for PR workflow:
    generateTargetBranch: true
    provider: github

出力：branch、commit、commitURL

git-open-pr

- uses: git-open-pr
  as: open-pr
  config:
    repoURL: https://github.com/example/repo.git
    provider: github
    sourceBranch: ${{ outputs['push'].branch }}
    targetBranch: main
    title: "Promote to ${{ ctx.stage }}"
    labels:
      - kargo
      - automated

出力：pr.id、pr.url

git-wait-for-pr

- uses: git-wait-for-pr
  config:
    repoURL: https://github.com/example/repo.git
    prNumber: ${{ outputs['open-pr'].pr.id }}
    provider: github

git-merge-pr

- uses: git-merge-pr
  config:
    repoURL: https://github.com/example/repo.git
    prNumber: ${{ outputs['open-pr'].pr.id }}
    wait: true

git-clear

- uses: git-clear
  config:
    path: ./out

設定管理

kustomize-set-image

- uses: kustomize-set-image
  config:
    path: ./out
    images:
    - image: ghcr.io/example/app
      tag: ${{ imageFrom(vars.imageRepo).Tag }}
    - image: ghcr.io/example/other
      newName: registry.example.com/other
      digest: ${{ imageFrom('ghcr.io/example/other').Digest }}

kustomize-build

- uses: kustomize-build
  config:
    path: ./src/overlays/test
    outPath: ./out/manifests.yaml
    plugin.helm.kubeVersion: "1.28.0"

helm-template

- uses: helm-template
  config:
    path: ./charts/my-chart
    outPath: ./out/manifests.yaml
    releaseName: my-release
    namespace: default
    outLayout: helm  # or 'flat'
    valuesFiles:
      - ./values-prod.yaml
    buildDependencies: true
    includeCRDs: true
    setValues:
      - key: image.tag
        value: ${{ imageFrom(vars.imageRepo).Tag }}

helm-update-chart

- uses: helm-update-chart
  config:
    path: ./src/my-chart
    charts:
      - repository: https://charts.example.com
        name: dependency-chart
        version: 2.0.0

yaml-update

- uses: yaml-update
  config:
    path: ./src/values.yaml
    updates:
      - key: image.tag
        value: ${{ imageFrom(vars.imageRepo).Tag }}
      - key: replicas
        value: "3"

json-update

- uses: json-update
  config:
    path: ./src/config.json
    updates:
      - key: version
        value: ${{ imageFrom(vars.imageRepo).Tag }}

ArgoCD 連携

argocd-update

- uses: argocd-update
  config:
    apps:
    - name: my-app
      namespace: argocd
      sources:
      - repoURL: https://github.com/example/repo.git
        desiredRevision: ${{ outputs.push.commit }}
        updateTargetRevision: true

必須のアプリケーションアノテーション：

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

ファイル操作

copy

- uses: copy
  config:
    inPath: ./overlay/kustomization.yaml
    outPath: ./src/kustomization.yaml

delete

- uses: delete
  config:
    path: ./temp

外部連携

http

- uses: http
  config:
    method: POST
    url: https://api.example.com/deploy
    headers:
      - name: Authorization
        value: "Bearer ${{ secrets.apiToken }}"
    body: '{"version":"${{ ctx.freight.displayID }}"}'
    timeout: 5m
    successExpression: response.status >= 200 && response.status < 300
    failureExpression: response.status >= 500

compose-output

- uses: compose-output
  config:
    pr_url: "${{ vars.repoURL }}/pull/${{ outputs['open-pr'].pr.id }}"
    commit_sha: "${{ outputs['commit'].commit }}"

式言語

構文

${{ expression }}

組み込み変数

変数	説明
ctx.project	プロジェクト名
ctx.stage	ステージ名
ctx.promotion	プロモーション名
ctx.freight	対象の Freight
vars.<name>	ユーザー定義変数
outputs.<step>.<field>	前のステップの出力

関数

アーティファクト関数

# Git commits
${{ commitFrom("https://github.com/example/repo.git").ID }}
${{ commitFrom("https://github.com/example/repo.git").Branch }}
${{ commitFrom("https://github.com/example/repo.git").Message }}
${{ commitFrom("https://github.com/example/repo.git").Author }}

# Container images
${{ imageFrom("public.ecr.aws/nginx/nginx").Tag }}
${{ imageFrom("public.ecr.aws/nginx/nginx").Digest }}
${{ imageFrom("public.ecr.aws/nginx/nginx").RepoURL }}

# Helm charts
${{ chartFrom("https://example.com/charts", "my-chart").Version }}
${{ chartFrom("https://example.com/charts", "my-chart").RepoURL }}

ステータス関数

# Conditional execution
if: ${{ success() }}      # All preceding steps succeeded
if: ${{ failure() }}      # Any preceding step failed
if: ${{ always() }}       # Always execute
if: ${{ status("my-step") == "Succeeded" }}

ユーティリティ関数

${{ quote(42) }}                    # Convert to quoted string
${{ configMap("my-config").key }}   # Read ConfigMap data
${{ secret("my-secret").password }} # Read Secret data
${{ warehouse("my-warehouse") }}    # Get Warehouse freight origin
${{ semverDiff("1.2.3", "1.3.0") }} # Returns: "Minor"

検証

AnalysisTemplate の構造

apiVersion: argoproj.io/v1alpha1
kind: AnalysisTemplate
metadata:
  name: integration-test
  namespace: my-project
spec:
  args:
    - name: commit
  metrics:
  - name: test-job
    provider:
      job:
        spec:
          template:
            spec:
              containers:
              - name: test
                image: alpine:latest
                command: ["sh", "-c", "sleep 10 && exit 0"]
              restartPolicy: Never
          backoffLimit: 1

ステージの検証設定

spec:
  verification:
    analysisTemplates:
      - name: integration-test
    analysisRunMetadata:
      labels:
        env: test
    args:
      - name: commit
        value: ${{ commitFrom("https://github.com/example/repo.git").ID }}

ソーク時間

spec:
  requestedFreight:
    - origin:
        kind: Warehouse
        name: my-warehouse
      sources:
        stages:
          - uat
        requiredSoakTime: 24h

パターン

イメージアップデーターパターン

単一のウェアハウスがイメージリポジトリを監視し、新しいバージョンごとに Freight を生成します。

設定アップデーターパターン

ウェアハウスが Git コミットを追跡し、ステージでベース設定とオーバーレイを組み合わせます。

一般的なパターン

1 つの Warehouse がイメージと Git リポジトリの両方をサブスクライブし、両方をまとめてプロモートします。

複数の Warehouse を使うパターン

イメージ用と設定用に Warehouse を分け、独立したプロモーションサイクルを可能にします。

サービスをグループ化するパターン

1 つの Warehouse が複数のリポジトリをサブスクライブし、連携したプロモーションを実現します。

分岐・合流パターン

分岐（A/B テストなど）と合流を含む非線形パイプラインです。

PR ワークフローパターン

steps:
  - uses: git-push
    config:
      generateTargetBranch: true
      provider: github

  - uses: git-open-pr
    as: open-pr
    config:
      targetBranch: main
      title: "Promote to ${{ ctx.stage }}"

  - uses: git-wait-for-pr
    config:
      prNumber: ${{ outputs['open-pr'].pr.id }}
      timeout: 48h

セキュリティ

OIDC の設定

api:
  oidc:
    enabled: true
    issuerURL: https://idp.example.com
    clientID: kargo-ui
    cliClientID: kargo-cli
    admins:
      claims:
        groups: [devops]
    projectCreators:
      claims:
        groups: [leads]

ユーザーと ServiceAccount のマッピング

apiVersion: v1
kind: ServiceAccount
metadata:
  name: admin
  namespace: my-project
  annotations:
    rbac.kargo.akuity.io/claims: |
      {
        "sub": ["alice", "bob"],
        "groups": ["devops", "kargo-admin"]
      }

定義済みのプロジェクトロール

• kargo-admin：プロジェクト管理のすべての権限
• kargo-viewer：読み取り専用アクセス
• default：Kubernetes が管理するベースライン

認証情報の管理

Git の認証情報

apiVersion: v1
kind: Secret
metadata:
  name: git-credentials
  namespace: my-project
  labels:
    kargo.akuity.io/cred-type: git
stringData:
  repoURL: https://github.com/example/repo.git
  username: my-username
  password: my-personal-access-token

SSH キー認証

apiVersion: v1
kind: Secret
metadata:
  name: git-ssh-credentials
  labels:
    kargo.akuity.io/cred-type: git
stringData:
  repoURL: [email protected]:example/repo.git
  sshPrivateKey: <base64-encoded-ssh-key>

GitHub App 認証

stringData:
  repoURL: https://github.com/example/repo.git
  githubAppClientID: "1234567"
  githubAppPrivateKey: <base64-encoded-app-key>
  githubAppInstallationID: "98765432"

コンテナレジストリの認証情報

AWS ECR：

metadata:
  labels:
    kargo.akuity.io/cred-type: image
stringData:
  repoURL: 123456789.dkr.ecr.us-west-2.amazonaws.com
  awsRegion: us-west-2
  awsAccessKeyID: AKIA...
  awsSecretAccessKey: ...

Google Artifact Registry：

stringData:
  repoURL: us-central1-docker.pkg.dev/my-project/my-repo
  gcpServiceAccountKey: |
    { "type": "service_account", ... }

CLI の認証情報管理

# Create credentials
kargo create credentials \
  --project my-project my-creds \
  --git \
  --repo-url https://github.com/example/repo.git \
  --username my-username \
  --password my-pat

# List credentials
kargo get credentials --project my-project

# Delete credentials
kargo delete credentials --project my-project my-creds

プロジェクトの設定

ProjectConfig リソース

apiVersion: kargo.akuity.io/v1alpha1
kind: ProjectConfig
metadata:
  name: my-project
  namespace: my-project
spec:
  promotionPolicies:
    - stages: ["test", "uat"]
      autoPromotionEnabled: true
    - stages: ["prod"]
      autoPromotionEnabled: false

  webhookReceivers:
    - name: github-webhook
      github:
        secretRef:
          name: github-secret

Namespace の管理

# Adopt pre-existing namespace
metadata:
  labels:
    kargo.akuity.io/project: "true"

# Preserve namespace after project deletion
metadata:
  annotations:
    kargo.akuity.io/keep-namespace: "true"

CLI コマンド

# Authentication
kargo login https://kargo.example.com --admin
kargo login https://kargo.example.com --sso

# Projects
kargo create project my-project
kargo get project my-project
kargo delete project my-project

# Stages
kargo create -f stage.yaml
kargo get stage my-stage --project my-project
kargo refresh stage my-stage --project my-project
kargo delete stage my-stage --project my-project

# Freight
kargo get freight --project my-project
kargo approve --project my-project --freight <id> --stage prod

# Promotions
kargo promote --project my-project --freight <id> --stage prod
kargo promote --project my-project --freight-alias my-alias --stage prod

# Verification
kargo verify stage my-stage --project my-project
kargo verify stage my-stage --project my-project --abort

# Roles
kargo get roles --project my-project
kargo create role developer --project my-project
kargo grant --role developer --claim groups=dev --project my-project
kargo delete role developer --project my-project

# Credentials
kargo get credentials --project my-project
kargo create credentials --project my-project my-creds --git --repo-url <url> --username <user> --password <token>
kargo update credentials --project my-project my-creds --password <new-token>
kargo delete credentials --project my-project my-creds

ステージの完全な例

apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
metadata:
  name: production
  namespace: my-project
spec:
  vars:
    - name: imageRepo
      value: ghcr.io/example/app
    - name: gitRepo
      value: https://github.com/example/deployment.git
    - name: gitBranch
      value: main
    - name: appName
      value: my-app

  requestedFreight:
    - origin:
        kind: Warehouse
        name: prod-warehouse
      sources:
        stages:
          - staging
        requiredSoakTime: 24h

  verification:
    analysisTemplates:
      - name: smoke-tests
    args:
      - name: imageTag
        value: ${{ imageFrom(vars.imageRepo).Tag }}

  promotionTemplate:
    spec:
      steps:
        - uses: git-clone
          as: clone
          config:
            repoURL: ${{ vars.gitRepo }}
            checkout:
              - branch: ${{ vars.gitBranch }}
                path: ./out

        - uses: kustomize-set-image
          config:
            path: ./out
            images:
              - image: ${{ vars.imageRepo }}
                tag: ${{ imageFrom(vars.imageRepo).Tag }}

        - uses: git-commit
          as: commit
          config:
            path: ./out
            message: |
              Promote to production
              Image: ${{ imageFrom(vars.imageRepo).Tag }}

        - uses: git-push
          as: push
          config:
            path: ./out
            targetBranch: ${{ vars.gitBranch }}

        - uses: argocd-update
          config:
            apps:
              - name: ${{ vars.appName }}
                sources:
                  - repoURL: ${{ vars.gitRepo }}
                    desiredRevision: ${{ outputs.push.commit }}
                    updateTargetRevision: true

参考資料

詳細なドキュメントについては、以下を参照してください。

• references/promotion-steps.md - プロモーションステップの完全なリファレンス
• references/expressions.md - 式言語のリファレンス
• references/patterns.md - デプロイパターン
• references/security.md - セキュリティ設定

公式ドキュメント

• メインドキュメント：https://docs.kargo.io/
• GitHub：https://github.com/akuity/kargo
• 例：https://github.com/akuity/kargo-examples