#使用模板构建 Python 流水线

该流水线旨在自动化 Python 应用的完整 CI/CD 工作流。
它具有可重用性和灵活性，支持自定义构建参数、多工作区以及步骤的条件执行。

主要特性：

• ✅ 灵活的代码来源
• 🔌 通过参数支持可插拔任务
• 🛠️ 动态镜像构建与推送
• ☁️ 通过 kubectl 更新工作负载镜像

#使用 hub 解析器指定

下面的示例 PipelineRun 引用了目录中的流水线：

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: python-pipeline-run
spec:
  pipelineRef:
    resolver: hub
    params:
    - name: catalog
      value: catalog
    - name: kind
      value: pipeline
    - name: name
      value: python-image-build-scan-deploy
    - name: version
      value: "0.1"

#参数

#Git Clone

• git-url

  • type: string
  • default: ""
  • description: 要克隆的仓库 URL。

• git-revision

  • type: string
  • default: ""
  • description: 要检出的版本（分支、标签、sha、ref 等）。

• skip-git-clone

  • type: string
  • default: "false"
  • description: 跳过执行 git clone 任务。仅当对应代码仓库已存在于工作区时可启用。

• git-crt-file-name

  • type: string
  • default: "ca-bundle.crt"
  • description: 使用 ssl-ca-directory 工作区挂载的 crt 文件名，默认值为 ca-bundle.crt。

#预构建

• pre-build-script

  • type: string
  • default: ""
  • description: 构建前执行的 python 脚本，可用于单元测试、代码检查、构建前运行脚本等。如果未设置此参数，将跳过 pre-build 任务。

• pre-build-args

  • type: array
  • default: []
  • description: 传递给预构建脚本的参数。

• pre-build-requirements-file

  • type: string
  • default: "requirements.txt"
  • description: 源代码位置内的依赖文件名，若无则回退到根目录下的 requirements 文件。

• pre-build-pip-conf-file

  • type: string
  • default: "pip.conf"
  • description: 自定义 pip 配置文件名。

#SonarQube Scanner

• sonar-url

  • type: string
  • default: ""
  • description: SonarQube 服务器实例的 URL，未指定则跳过 sonarqube 扫描任务。

• sonar-project-key

  • type: string
  • default: ""
  • description: SonarQube 项目的唯一键。

• sonar-properties

  • type: array
  • default: ["sonar.sources=."]
  • description: 传递给 SonarQube 的额外属性。详情可参考 SonarQube 属性配置。

#构建镜像

• images

  • type: array
  • description: buildah 生成的镜像引用。可包含多个以逗号分隔的镜像地址，例如：
    • busybox:latest
    • busybox:v1 .30.1

• dockerfile-path

  • type: string
  • default: ./Dockerfile
  • description: Dockerfile 的路径。

• build-extra-args

  • type: string
  • default: ""
  • description: 构建镜像时传递给 build 命令的额外参数。警告 - 必须进行安全过滤以避免命令注入（例如 --build-arg key=value --label key=value）。

• build-args

  • type: array
  • default: [""]
  • description: 指定构建参数及其值，会在 Dockerfile 指令中进行插值，但不会加入最终镜像配置的环境变量列表。例如 HTTP_PROXY=http://10.10.10.10:8080 。

• build-context

  • type: string
  • default: .
  • description: 用作构建上下文的目录路径。

• push-extra-args

  • type: string
  • default: ""
  • description: 推送镜像时传递给 push 命令的额外参数。警告 - 必须进行安全过滤以避免命令注入（例如 --creds=username:password ）。

#Trivy 扫描器

• skip-trivy-scan

  • type: string
  • default: "false"
  • description: 设置为跳过构建后的 trivy 镜像扫描。

• trivy-extra-args

  • type: string
  • default: ""
  • description: 扫描镜像时传递给 trivy 命令的额外参数。警告 - 必须进行安全过滤以避免命令注入（例如 --insecure）。可使用 --skip-db-update 和 --skip-java-db-update 跳过漏洞数据库更新。

#部署或升级工作负载

• workload-name

  • type: string
  • default: ""
  • description: 要部署或升级的工作负载名称。未指定则跳过 deploy-or-upgrade 任务。

• workload-kind

  • type: string
  • default: Deployment
  • description: 要部署或升级的工作负载类型，如 Deployment、StatefulSet 等。

• workload-namespace

  • type: string
  • default: ""
  • description: 工作负载所在的命名空间，未指定则使用当前 TaskRun 的命名空间。

• workload-container

  • type: string
  • default: []
  • description: 指定需要更新镜像的工作负载中的容器。默认情况下，工作负载中所有容器的镜像都会被更新。

• workload-rollout-timeout

  • type: string
  • default: "0"
  • description: 等待工作负载准备就绪的超时时间，0 表示永不超时。其他值应包含时间单位（例如 1s、2m、3h）。

• workload-manifests-dir

  • type: string
  • default: ""
  • description: 部署工作负载的清单目录。未指定时，仅更新集群中已有工作负载的镜像。可使用相对于 source 工作区的清单目录路径，例如 "manifests"。

#工作区

• source：用于任务间共享信息的工作区。
• git-basic-auth：一个可选工作区，包含 .gitconfig 和 .git-credentials 文件，执行 git 命令前会复制到用户主目录。工作区中其他文件会被忽略。强烈建议优先使用 ssh-directory 并绑定 Secret，而非 basic-auth 或其他卷类型。
• git-ssh-directory：一个可选工作区，包含私钥、known_hosts、config 等，执行 git 命令前复制到用户主目录。用于 git clone 时的远程认证。强烈建议绑定 Secret 优于其他卷类型。
• git-ssl-ca-directory：一个可选工作区，包含 CA 证书，Git 在通过 HTTPS 拉取或推送时用于验证对端。
• pip-conf：一个可选工作区，包含自定义 pip 配置。
• sonar-settings：一个可选工作区，用于挂载 SonarQube 属性。
• sonar-credentials：一个可选工作区，包含 SonarQube 使用的凭据。
• dockerconfig：一个可选工作区，用于分发注册表配置文件，如 config.json 或 .dockerconfigjson，用于推送镜像时的认证。
• kubeconfig：一个可选工作区，包含 kubeconfig 文件。kubeconfig 文件名应为 kubeconfig，若无则忽略该工作区。

#平台

该 Task 可在 linux/amd64 和 linux/arm64 平台运行。

#使用

#最小配置：使用最少参数运行端到端流水线

未设置或省略的可选任务（如 sonarqube-scanner、deploy-or-upgrade 等）将被优雅地跳过。

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  generateName: python-build-run-
spec:
  pipelineRef:
    name: python-image-build-scan-deploy
  params:
    - name: git-url
      value: https://github.com/example/python-app
    - name: git-revision
      value: refs/heads/main
    - name: images
      value: ["registry.example.com/python-app:latest"]
  workspaces:
    - name: source
      persistentVolumeClaim:
        claimName: source
    - name: git-basic-auth
      secret:
        secretName: gitconfig
    - name: dockerconfig
      secret:
        secretName: dockerconfig

#SonarQube 属性配置

你可以挂载 sonar-settings 工作区，或使用 sonar-properties 参数来应用 sonar-project.properties 文件的属性。

默认属性为：sonar.sources=.。

你可以参考 分析参数 和 Python 语言属性 来了解 SonarQube 属性的用法。

以下是部分可设置的属性：

#部署或升级工作负载

你可以使用该流水线中 build-image 任务构建的镜像来部署或升级工作负载。

通过设置 workload-manifests-dir 参数，可以从指定目录应用 Kubernetes 清单来创建或更新工作负载。

支持 JSON 和 YAML 格式。指定目录下的所有清单文件将通过 kubectl apply 处理。注意 kubectl apply 不会递归子目录。

如果目录中包含 Kustomize 配置文件（例如 kustomization.yaml、kustomization.yml 或 Kustomization），则会使用 kubectl kustomize 进行处理。

以下是 workload-manifests-dir 的示例结构：

manifests
├── deployment.yaml
├── kustomization.yaml
└── service.yaml

你可以配置以下参数：

spec:
  params:
    # ...
    - name: images
      value:
        - foo/bar:latest
    - name: workload-name
      value: bar
    - name: workload-namespace
      value: default
    - name: workload-kind
      value: Deployment
    - name: workload-manifests-dir
      value: manifests
    # ...

如果不想使用清单部署工作负载，只需将 workload-manifests-dir 参数留空。此时任务仅更新集群中已有工作负载的镜像。

你需要自行管理工作负载的镜像拉取密钥。如果新镜像托管在不同的注册表，请确保为工作负载创建并配置相应的拉取密钥。

#运行 pytest

你可以使用该流水线中的 pre-build 任务运行 pytest。

下面是运行 pytest 的示例：

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  generateName: python-build-run-
spec:
  pipelineRef:
    name: python-image-build-scan-deploy
  params:
    - name: git-url
      value: https://github.com/example/python-app
    - name: git-revision
      value: refs/heads/main
    - name: images
      value: ["registry.example.com/python-app:latest"]
    - name: pre-build-script
      value: |
        pytest
  workspaces:
    - name: source
      persistentVolumeClaim:
        claimName: source
    - name: git-basic-auth
      secret:
        secretName: gitconfig
    - name: dockerconfig
      secret:
        secretName: dockerconfig

#使用参数跳过任务

流水线支持通过参数跳过任务：

#全任务示例

此示例展示如何使用流水线中的所有任务，包括：

• 克隆源代码
• 使用预构建任务运行单元测试
• 构建镜像并推送到注册表
• 使用 Trivy 扫描镜像
• 使用 SonarQube 扫描代码
• 部署或升级工作负载

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  generateName: python-build-run-
spec:
  pipelineRef:
    name: python-image-build-scan-deploy
  params:
    - name: git-url
      value: https://github.com/example/python-app
    - name: git-revision
      value: refs/heads/main
    - name: sonar-url
      value: https://sonar.example.com
    - name: sonar-project-key
      value: python-pipeline-example-key
    - name: images
      value: ["registry.example.com/python-app:latest"]
    - name: workload-name
      value: python-app
    - name: workload-namespace
      value: default
    - name: pre-build-script
      value: |
        pytest
  workspaces:
    - name: source
      persistentVolumeClaim:
        claimName: source
    - name: git-basic-auth
      secret:
        secretName: gitconfig
    - name: sonar-credentials
      secret:
        secretName: sonar-credentials
    - name: dockerconfig
      secret:
        secretName: registry-creds
    - name: kubeconfig
      configMap:
        name: kubeconfig