Alauda DevOps Pipelines Docs
  • 简体中文

    • 打包并推送 Helm Chart 到 OCI 仓库

    本指南将带你完成一个实际的 CI 场景：你的 Git 仓库已经包含了一个 Helm chart（Chart.yaml、templates/、values.yaml 等）。

    我们将使用 Pipeline 来：

    1. 使用 git-clone Task 克隆仓库
    2. 使用 Helm 打包 chart
    3. 将构建好的 chart 推送到 OCI 仓库（例如 Harbor）

    你将创建一个包含两个 Tasks 的 Pipeline：

    1. git-clone：将你的仓库克隆到共享工作空间
    2. helm：打包 chart 并将 .tgz 推送到你的 OCI 仓库

    目录

    前提条件逐步操作指南第 1 步：创建仓库凭证 Secret第 2 步：准备 helm 镜像第 3 步：定义 Pipeline第 4 步：使用 PipelineRun 运行故障排查后续步骤

    前提条件

    • 一个 Kubernetes 集群（你可以使用 minikube 进行本地测试）。
    • 在集群上安装了 Tekton Pipelines。
    • 一个 Helm 3.8+ 容器镜像（支持 OCI 的 Helm v3）。
    • 一个 OCI 仓库及仓库路径（例如 oci://registry.example.com/charts）。
    • 用于 OCI 仓库推送的凭证，作为类型为 kubernetes.io/dockerconfigjson 的 Secret：
      • 创建一个类型为 kubernetes.io/dockerconfigjson 的 Kubernetes Secret（示例见下文）。
    • 一个包含有效 Helm chart 的 Git 仓库（包含 Chart.yaml、templates/、values.yaml 的目录）。
    • 访问该 Git 仓库的权限：
      • 公开仓库：无需特殊处理。
      • 私有仓库：创建 Git 凭证 Secret（SSH 或基本认证）。

    为什么要使用类型为 kubernetes.io/dockerconfigjson 的 Secret？我们将通过 HELM_REGISTRY_CONFIG 指向分发仓库。

    逐步操作指南

    第 1 步：创建仓库凭证 Secret

    你需要为你的 OCI 仓库创建一个类型为 kubernetes.io/dockerconfigjson 的凭证 Secret。

    你可以参考 Prepare Registry Credential。

    第 2 步：准备 helm 镜像

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

    你可以参考 Discover Tool Image。

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

    第 3 步：定义 Pipeline

    该 Pipeline 使用 git-clone 获取你的仓库，然后调用 helm 打包并推送 chart。

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

    apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: package-and-push-helm-oci
spec:
  description: Clone repo, package Helm chart, and push to an OCI registry.
  params:
    - name: repo_url
      type: string
      description: Git URL of your repository
    - name: revision
      type: string
      description: Git revision (branch, tag, or SHA)
      default: main
    - name: chart_dir
      type: string
      description: Path to the Helm chart in the repo
      default: "."
    - name: oci_repo
      type: string
      description: OCI repo, e.g., oci://registry.example.com/charts
    - name: package_flags
      type: string
      description: Extra flags for `helm package`
      default: ""
  workspaces:
    - name: source
    - name: registry-creds
      optional: true
    - name: basic-auth
      optional: true
  tasks:
    - name: git-clone
      taskRef:
        resolver: hub
        params:
          - name: catalog
            value: catalog
          - name: kind
            value: task
          - name: name
            value: git-clone
          - name: version
            value: "0.9"
      workspaces:
        - name: output
          workspace: source
        - name: basic-auth
          workspace: basic-auth
      params:
        - name: url
          value: $(params.repo_url)
        - name: revision
          value: $(params.revision)
    - name: helm
      runAfter:
        - "git-clone"
      taskRef:
        resolver: hub
        params:
          - name: catalog
            value: catalog
          - name: kind
            value: task
          - name: name
            value: run-script
          - name: version
            value: "0.1"
      workspaces:
        - name: source
          workspace: source
        - 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

            echo "Packaging chart from $(params.chart_dir)"
            tempDir=$(mktemp -d)
            helm package $(params.chart_dir) --destination ${tempDir} $(params.package_flags)

            chart_tgz="$(ls ${tempDir}/*.tgz | head -n1)"
            if [ -z "${chart_tgz}" ]; then
              echo "No packaged chart found!"
              exit 1
            fi
            echo "Packaged: ${chart_tgz}"

            echo "Pushing to $(params.oci_repo)..."
            helm push "${chart_tgz}" "$(params.oci_repo)"

            echo "Done."

    第 4 步：使用 PipelineRun 运行

    绑定工作空间并传入参数。

    apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  generateName: package-and-push-helm-oci-
spec:
  pipelineRef:
    name: package-and-push-helm-oci
  workspaces:
    - name: source
      volumeClaimTemplate:
        spec:
          ## Specify StorageClassName (as needed)
          # storageClassName: <storage-class-name>
          accessModes:
            - ReadWriteOnce
          resources:
            requests:
              storage: 1Gi
    - name: registry-creds
      secret:
        secretName: registry-creds
    - name: basic-auth
      secret:
        secretName: basic-auth
  params:
    - name: repo_url
      value: https://github.com/your-org/your-repo.git
    - name: revision
      value: main
    - name: oci_repo
      value: oci://registry.example.com/charts
    - name: chart_dir
      value: .

    故障排查

    • helm: command not found：确认你的 image 中确实包含 Helm 二进制文件。
    • Error: unknown command "push"：你的 Helm 镜像不支持 OCI push。请使用更新的 Helm（3.8+）镜像。
    • unauthorized: authentication required：确认 Secret 正确且已挂载到 registry-creds。确认 HELM_REGISTRY_CONFIG 已设置为该路径。

    后续步骤