Alauda DevOps Pipelines Docs
简体中文

使用模板构建 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 扫描器

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

支持平台

该任务可运行于 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 属性的使用。

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

属性描述
sonar.python.version默认情况下，Python 代码被同时兼容 Python 2 和 Python 3 进行分析。为了获得更精确的分析结果，可以通过 sonar.python.version 参数指定代码支持的 Python 版本。
sonar.qualitygate.wait强制分析步骤轮询服务器实例并等待质量门状态。
sonar.qualitygate.timeout扫描器等待报告处理的秒数。
sonar.projectVersion项目版本。用于基于先前版本的新代码定义的分支分析时应设置此项。
sonar.sources包含主要源文件的目录路径，多个路径用逗号分隔。
sonar.organizationSonarQube 中项目所属的组织。

部署或升级工作负载

你可以使用流水线中 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

使用参数跳过任务

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

任务参数默认值描述
git-cloneskip-git-clone"false"如果代码已存在于 source 工作区，可设置为 "true" 跳过克隆。
pre-buildpre-build-script""未设置 pre-build-script 时跳过预构建任务。
sonarqube-scannersonar-url""未设置 sonar-url 时跳过扫描。
trivy-scannerskip-trivy-scan"false"设置为 "true" 时跳过扫描。
deploy-or-upgradeworkload-name""不想部署或升级工作负载时，可将 workload-name 留空。

包含所有任务的完整示例

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

  • 克隆源代码
  • 使用预构建任务运行单元测试
  • 构建镜像并推送到镜像仓库
  • 使用 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: docker-credentials
    - name: kubeconfig
      configMap:
        name: kubeconfig