kargo-skill

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（默认）：至少需要在一个上游阶段中完成验证
• 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

必需的 Application 注解：

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 提交，阶段将基础配置与覆盖配置组合起来。

常见场景模式

单个 Warehouse 同时订阅镜像仓库和 Git 仓库，并将二者一起晋级。

多 Warehouse 模式

为镜像和配置分别设置 Warehouse，以便独立安排晋级节奏。

服务分组模式

单个 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

命名空间管理

# 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

完整的 Stage 示例

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