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

本指南展示了一个实际的 CD 路径,假设您的 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。

可参考 Prepare Registry Credential。

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

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

可参考 Prepare Cluster Access Credential。

第 3 步:准备 helm 镜像

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

可参考 Discover Tool Image。

搜索时通过标签指定镜像为 helm,例如:-l operator.tekton.dev/tool-image=helm。

第 4 步:定义 Pipeline

该 Pipeline 使用 helm upgrade --install 直接从 OCI chart 引用安装/升级 release。

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

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

通常会结合 --atomic,如果等待失败或超时会自动回滚,避免留下半升级状态的 release。

请将 <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 引用,例如 oci://registry.example.com/charts/myapp
    - name: version
      type: string
      description: 要安装/升级到的 chart 版本(必须存在于注册表中)
    - name: release_name
      type: string
      description: Helm release 名称
    - name: namespace
      type: string
      description: 目标命名空间
      default: default
    - name: extra_args
      type: string
      description: 额外的 helm 参数(例如 "--atomic --timeout 5m --set key=val -f values.yaml")
      default: ""
  workspaces:
    - name: registry-creds
      description: 包含分发注册表配置的工作空间,配置文件为 config.json(用于 OCI 认证)
      optional: true
    - name: kubeconfig
      description: 包含 kubeconfig 文件的工作空间,文件路径为 ./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
          ## 替换为您的 Helm 镜像
          value: <helm-image>
        - name: script
          value: |
            if [ "$(workspaces.secret.bound)" = "true" ]; then
              echo "使用注册表凭证,路径:$(workspaces.secret.path)"
              export HELM_REGISTRY_CONFIG=$(workspaces.secret.path)/.dockerconfigjson
            fi

            if [ "$(workspaces.config.bound)" = "true" ]; then
              echo "使用 kubeconfig,路径:$(workspaces.config.path)"
              export KUBECONFIG=$(workspaces.config.path)/kubeconfig
            fi

            echo "升级/安装 release..."
            echo "  Release:   $(params.release_name)"
            echo "  Namespace: $(params.namespace)"
            echo "  Chart:     $(params.oci_chart):$(params.version)"

            # 直接从 OCI 安装(无需先 helm pull)
            helm upgrade --install "$(params.release_name)" "$(params.oci_chart)" \
              --version "$(params.version)" \
              --namespace "$(params.namespace)" --create-namespace \
              $(params.extra_args)

            echo "完成。"

第 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

    ## 如果选择使用 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

  ## 如果选择使用 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 管理资源所需的角色。

后续步骤