Alauda DevOps Pipelines Docs
  • 简体中文

    • 使用 OCI 仓库中的 Helm Chart 部署/升级

    本指南展示了一个实际的持续交付路径，假设您的 Helm Chart 已经推送到 OCI 注册表（例如 Harbor）。

    您将使用 Tekton Pipeline 将该 Chart 拉取并安装到 Kubernetes 集群中。

    您将构建一个可复用的 Pipeline，名为 helm-oci-deploy，它将：

    1. 认证您的 OCI 注册表
    2. 直接从 OCI Chart 引用运行 helm upgrade --install
    3. 可选地应用额外的 values 文件和 --set 覆盖参数
    4. 支持使用 Kubeconfig Secret 或 ServiceAccount

    目录

    前提条件

    • 一个 Kubernetes 集群（本地测试可使用 minikube）。
    • 集群中已安装 Tekton Pipelines。
    • 一个 Helm 3.8+ 容器镜像（支持 Helm v3 的 OCI 功能）。
    • 一个包含您要部署的 OCI Chart 引用和版本的 OCI 注册表，例如：
      • oci://registry.example.com/charts/myapp
      • 版本如 1.2.3（必须存在于注册表中）
    • 用于您的 OCI 注册表的凭证，作为类型为 kubernetes.io/dockerconfigjson 的 Secret：
      • 创建一个类型为 kubernetes.io/dockerconfigjson 的 Kubernetes Secret（示例见下）。
    • Helm 的集群访问权限（任选其一）：
      • 挂载 Kubeconfig Secret，
      • 在具有足够 RBAC 权限的 ServiceAccount 下运行 Task。

    逐步操作指南

    第 1 步：创建注册表凭证 Secret

    您需要为您的 OCI 注册表创建一个类型为 kubernetes.io/dockerconfigjson 的注册表凭证 Secret。

    可参考准备注册表凭证。

    第 2 步：创建集群访问凭证

    您需要为 Helm 创建集群访问凭证。

    可参考准备集群访问凭证。

    第 3 步：准备 helm 镜像

    您需要一个 Helm 3.8+ 容器镜像（支持 Helm v3 的 OCI 功能）来运行 helm 命令。

    可参考发现工具镜像。

    搜索时请指定镜像标签为 helm，例如：-l operator.tekton.dev/tool-image=helm。

    第 4 步：定义 Pipeline

    该 Pipeline 使用 helm upgrade --install 直接从 OCI Chart 引用安装/升级发布。

    Helm 3.8+ 支持通过 oci://... 和 --version 引用 Chart，使步骤无状态且快速。 如果您更倾向于预先拉取 Chart，可以先用 helm pull 下载到临时目录，再从 .tgz 路径安装。

    您可以使用 --wait 阻塞直到 Kubernetes 报告发布的资源就绪（或操作超时）。 配合 --timeout 控制 Helm 等待时长。

    通常会搭配 --atomic 使用，若等待失败或超时会自动回滚，避免发布处于半升级状态。

    请将 <helm-image> 替换为您的 Helm 镜像。

    apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: helm-oci-deploy
spec:
  description: Clone repo, package Helm chart, and push to an OCI registry.
  params:
    - name: oci_chart
      type: string
      description: OCI chart ref, e.g. oci://registry.example.com/charts/myapp
    - name: version
      type: string
      description: Chart version to install/upgrade to (must exist in the registry)
    - name: release_name
      type: string
      description: Helm release name
    - name: namespace
      type: string
      description: Target namespace
      default: default
    - name: extra_args
      type: string
      description: Extra helm args (e.g., "--atomic --timeout 5m --set key=val -f values.yaml")
      default: ""
  workspaces:
    - name: registry-creds
      description: Workspace with distribution registry config at config.json (for OCI auth)
      optional: true
    - name: kubeconfig
      description: Workspace containing kubeconfig file at ./kubeconfig
      optional: true
  tasks:
    - name: helm
      taskRef:
        resolver: hub
        params:
          - name: catalog
            value: catalog
          - name: kind
            value: task
          - name: name
            value: run-script
          - name: version
            value: "0.1"
      workspaces:
        - name: config
          workspace: kubeconfig
        - name: secret
          workspace: registry-creds
      params:
        - name: image
          ## Replace with your Helm image
          value: <helm-image>
        - name: script
          value: |
            if [ "$(workspaces.secret.bound)" = "true" ]; then
              echo "Using registry credentials in $(workspaces.secret.path)"
              export HELM_REGISTRY_CONFIG=$(workspaces.secret.path)/.dockerconfigjson
            fi

            if [ "$(workspaces.config.bound)" = "true" ]; then
              echo "Using kubeconfig in $(workspaces.config.path)"
              export KUBECONFIG=$(workspaces.config.path)/kubeconfig
            fi

            echo "Upgrading/Installing release..."
            echo "  Release:   $(params.release_name)"
            echo "  Namespace: $(params.namespace)"
            echo "  Chart:     $(params.oci_chart):$(params.version)"

            # Direct install from OCI (no need to helm pull first)
            helm upgrade --install "$(params.release_name)" "$(params.oci_chart)" \
              --version "$(params.version)" \
              --namespace "$(params.namespace)" --create-namespace \
              $(params.extra_args)

            echo "Done."

    第 5 步：使用 PipelineRun 运行

    • Helm 的集群访问权限（任选其一）：
      • 挂载 Kubeconfig Secret，
      • 在具有足够 RBAC 权限的 ServiceAccount 下运行 Task。

    请选择一种集群访问凭证。

    apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  generateName: helm-oci-deploy-
spec:
  workspaces:
    - name: registry-creds
      secret:
        secretName: registry-creds

    ## If you choose to use the kubeconfig Secret
    # - name: kubeconfig
    #   secret:
    #     secretName: <kubeconfig-secret-name>

  params:
    - name: oci_chart
      value: oci://registry.example.com/charts/myapp
    - name: version
      value: "1.1.0"
    - name: release_name
      value: myapp
    - name: namespace
      value: my-namespace
  pipelineRef:
    name: helm-oci-deploy

  ## If you choose to use the ServiceAccount
  # taskRunTemplate:
  #   serviceAccountName: <service-account-name>

    故障排查

    • helm: command not found：确认您的 image 中确实包含 Helm 二进制文件。
    • unauthorized: authentication required：确认 Secret 正确且已挂载到 registry-creds。确认 HELM_REGISTRY_CONFIG 设置为该路径。
    • Error: chart "myapp" version "x.y.z" not found：该版本在 OCI 仓库中不存在或 oci_chart 路径错误。请核实推送的标签/版本和路径。
    • failed to create resource: (…RBAC…) forbidden：kubeconfig 或 ServiceAccount 缺少权限。请授予创建/更新 Chart 管理资源所需的角色。

    后续步骤