rancher-docs/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/pipelines/pipeline-configuration.md

title

title
流水线配置参考

在本文中，你将学习如何配置流水线。

步骤类型

在每个阶段中，你都可以添加任意数量的步骤。一个阶段中的多个步骤会并发运行。

步骤类型包括：

• 运行脚本
• 构建和发布镜像
• 发布商店应用模板
• 部署 YAML
• 部署商店应用

通过 UI 配置步骤

如果你还没有添加任何阶段，请单击为此分支配置流水线以在 UI 中配置流水线。

1. 通过单击添加阶段将阶段添加到流水线执行中。

   1. 输入流水线中各个阶段的名称。
   2. 你可以单击显示高级选项来配置触发阶段的规则。注意，你之后还可以更新它们。

2. 创建阶段后，单击添加步骤来开始添加步骤。你可以向每个阶段添加多个步骤。

通过 YAML 配置步骤

你可以在每个阶段中添加多个步骤。如需了解如何配置 YAML，请阅读每个步骤类型和高级选项的更多信息。以下是一个小示例，说明如何配置多个阶段，其中各个阶段中都只有一个步骤：

# 示例
stages:
  - name: Build something
    # 阶段的条件
    when:
      branch: master
      event: [ push, pull_request ]
    # 多个步骤并发运行
    steps:
      - runScriptConfig:
          image: busybox
          shellScript: date -R
  - name: Publish my image
    steps:
    - publishImageConfig:
        dockerfilePath: ./Dockerfile
        buildContext: .
        tag: rancher/rancher:v2.0.0
        # 可选择推送到远端镜像仓库
        pushRemote: true
        registry: reg.example.com

步骤类型：运行脚本

运行脚本步骤用于在指定容器内的工作空间中执行命令。你可以根据基础镜像提供的实用程序，使用这个步骤来构建、测试，以及执行更多其他操作。为方便起见，你可以使用变量来引用流水线执行的元数据。有关可用变量的列表，请参阅流水线变量替换参考。

通过 UI 配置脚本

1. 从步骤类型下拉列表中，选择运行脚本并填写表单。

2. 单击添加。

通过 YAML 配置脚本

# 示例
stages:
- name: Build something
  steps:
  - runScriptConfig:
      image: golang
      shellScript: go build

步骤类型：构建和发布镜像

构建和发布镜像步骤用于构建并发布 Docker 镜像。此步骤需要源代码仓库中的 Dockerfile。

UI 中不提供将镜像发布到不安全镜像仓库的选项。但你可以在 YAML 中指定一个环境变量，从而将镜像发布到不安全的镜像仓库。

通过 UI 配置镜像的构建和发布

1. 从步骤类型下拉菜单中，选择构建和发布。

2. 完成表单的剩余部分。下面列出了每个字段的说明。完成后，请单击添加。

   字段	描述
   Dockerfile 路径	源代码仓库中 Dockerfile 的相对路径。如果 Dockerfile 位于根目录，则默认路径为 ./Dockerfile。你可以在不同用例中将其设置为其他路径（例如 ./path/to/myDockerfile）。
   镜像名称	name:tag 格式的镜像名称。不需要填写镜像仓库地址。例如，如果要构建 example.com/repo/my-image:dev，请输入 repo/my-image:dev。
   将镜像推送到远端仓库	设置用于发布已构建的镜像的镜像仓库。要使用此选项，请启用它并从下拉列表中选择一个镜像仓库。如果禁用此选项，则将镜像推送到内部镜像仓库。
   构建上下文 （显示高级选项）	默认是源代码的根目录 (.)。有关更多详细信息，请参阅 Docker 构建命令文档。

通过 YAML 配置镜像的构建和发布

你可以为 Docker daemon 和构建使用特定参数。UI 中没有开放这些参数，但你能以流水线 YAML 格式配置这些参数，如下例所示。可用的环境变量包括：

变量名称	描述
PLUGIN_DRY_RUN	禁用 Docker push
PLUGIN_DEBUG	Docker daemon 在调试模式下执行
PLUGIN_MIRROR	Docker daemon 镜像仓库 mirror
PLUGIN_INSECURE	Docker daemon 允许不安全的镜像仓库
PLUGIN_BUILD_ARGS	Docker 构建参数（逗号分隔的列表）

# 此示例展示了在"推送镜像"步骤中使用的环境变量。
# 此变量允许你
# 将镜像发布到不安全的镜像仓库：

stages:
- name: Publish Image
  steps:
  - publishImageConfig:
      dockerfilePath: ./Dockerfile
      buildContext: .
      tag: repo/app:v1
      pushRemote: true
      registry: example.com
    env:
      PLUGIN_INSECURE: "true"

步骤类型：发布商店应用模板

发布商店应用模板步骤将商店应用模板的版本（即 Helm Chart）发布到 Git 托管的镜像仓库。它生成一个 Git commit 并将其推送到你的 chart 仓库。要让这个步骤成功完成，需要源代码仓库中的 Chart 文件夹和专用流水线命名空间中的预配置密文。Chart 文件夹中的任何文件都支持流水线变量替换参考中的变量。

通过 UI 配置发布商店应用的模板

1. 从步骤类型下拉菜单中，选择发布商店应用模板。

2. 完成表单的剩余部分。下面列出了每个字段的说明。完成后，请单击添加。

   字段	描述
   Chart 文件夹	Chart.yaml 文件所在的源代码仓库中， chart 文件夹的相对路径。
   商店应用模板名称	模板的名称。例如，wordpress。
   商店应用模板版本	你要发布的模板版本，应该和 Chart.yaml 文件中定义的版本一致。
   协议	可以选择使用 HTTP(S) 或 SSH 协议发布。
   密文	存储 Git 凭证的密文。在添加此步骤之前，你需要在项目的专用流水线命名空间中创建一个密文。如果你使用 HTTP(S) 协议，请将 Git 用户名和密码存储在密文的 USERNAME 和 PASSWORD 键中。如果你使用 SSH 协议，请将 Git 部署密钥存储在密文的 DEPLOY_KEY 中。创建密文后，在此选项中选择它。
   Git URL	用于发布模板的 chart 仓库的 Git URL。
   Git 分支	用于发布模板的 chart 仓库的 Git 分支。
   提交者姓名	Commit 消息中使用的提交者姓名。
   提交者邮箱	Commit 消息中使用的提交者邮箱。

通过 YAML 配置发布商店应用的模板

你可以直接在 .rancher-pipeline.yml 文件中添加发布商店应用模板步骤。

在 steps 中，使用 publishCatalogConfig 添加一个步骤。你需要提供以下信息：

• Path：Chart.yaml 文件所在的源代码仓库中， chart 文件夹的相对路径。
• CatalogTemplate：模板的名称。
• Version：你要发布的模板版本，应该和 Chart.yaml 文件中定义的版本一致。
• GitUrl：用于发布模板的 chart 仓库的 Git URL。
• GitBranch：用于发布模板的 chart 仓库的 Git 分支。
• GitAuthor：Commit 消息中使用的提交者姓名。
• GitEmail：Commit 消息中使用的提交者邮箱。
• Credentials：需要通过引用专用流水线命名空间中的密文来提供 Git 凭证。如果你使用 SSH 协议进行发布，请将部署密钥保存在 DEPLOY_KEY 环境变量中。如果你使用 HTTP(S) 协议进行发布，请将你的用户名和密码保存在 USERNAME 和 PASSWORD 环境变量中。

# 示例
stages:
- name: Publish Wordpress Template
  steps:
  - publishCatalogConfig:
      path: ./charts/wordpress/latest
      catalogTemplate: wordpress
      version: ${CICD_GIT_TAG}
      gitUrl: git@github.com:myrepo/charts.git
      gitBranch: master
      gitAuthor: example-user
      gitEmail: user@example.com
    envFrom:
    - sourceName: publish-keys
      sourceKey: DEPLOY_KEY

步骤类型：部署 YAML

此步骤将任意 Kubernetes 资源部署到项目中。此部署需要 Kubernetes 清单文件存在于源代码仓库中。清单文件中支持流水线变量替换。你可以在 GitHub 中查看​​示例文件。有关可用变量的列表，请参阅流水线变量替换参考。

通过 UI 配置 YAML 的部署

1. 从步骤类型下拉列表中，选择部署 YAML 并填写表单。

2. 输入 YAML 路径，即源代码中清单文件的路径。

3. 单击添加。

通过 YAML 配置 YAML 的部署

# 示例
stages:
- name: Deploy
  steps:
  - applyYamlConfig:
      path: ./deployment.yaml

步骤类型：部署商店应用

部署商店应用步骤用于在项目中部署商店应用。如果应用不存在，则将安装一个新应用，或升级现有应用。

通过 UI 配置商店应用的部署

1. 从步骤类型下拉菜单中，选择部署商店应用。

2. 完成表单的剩余部分。下面列出了每个字段的说明。完成后，请单击添加。

   字段	描述
   Catalog	将使用应用模板的商店应用。
   模板名称	应用模板的名称。例如，wordpress。
   模板版本	要部署的应用模板的版本。
   命名空间	要部署应用的目标命名空间。
   应用名称	要部署的应用的名称。
   答案	用于部署应用的答案的键值对。

通过 YAML 配置商店应用的部署

你可以直接在 .rancher-pipeline.yml 文件中添加部署商店应用步骤。

在 steps 中，使用 applyAppConfig 添加一个步骤。你需要提供以下信息：

• CatalogTemplate：模板的 ID。你可以单击启动应用，并选择该应用的查看详情来找到 ID。它是 URL 的最后一部分。
• Version：要部署的模板的版本。
• Answers：用于部署应用的答案的键值对。
• Name：要部署的应用的名称。
• TargetNamespace：要部署应用的目标命名空间。

# 示例
stages:
- name: Deploy App
  steps:
  - applyAppConfig:
      catalogTemplate: cattle-global-data:library-mysql
      version: 0.3.8
      answers:
        persistence.enabled: "false"
      name: testmysql
      targetNamespace: test

超时

默认情况下，每个流水线执行的超时时间为 60 分钟。如果流水线执行无法在超时期限内完成，则流水线将中止。

通过 UI 配置超时

在超时字段中输入所需的值。

通过 YAML 配置超时

在 timeout 中，输入超时值（以分钟为单位）。

# 示例
stages:
  - name: Build something
    steps:
    - runScriptConfig:
        image: busybox
        shellScript: ls
# 以分钟为单位的超时
timeout: 30

通知

你可以根据流水线的构建状态，启用对通知器的通知。在启用通知之前，Rancher 建议你先设置通知器，以便立即添加收件人。

通过 UI 配置通知

1. 在通知中，单击启用以打开通知。

2. 选择通知的条件。你可以选择接收以下状态的通知：失败、成功或已更改。例如，如果你想在执行失败时接收通知，请选择失败。

3. 如果你没有现有的通知器，Rancher 会提示未设置通知器的警告，并显示跳转到通知器页面的链接。你可以按照说明添加通知器。如果你已经有通知器，你可以单击添加收件人按钮，将他们添加到通知中。

   :::note

   通知器是在集群级别配置的，需要不同级别的权限。

   :::

4. 在下拉列表中为每个收件人选择通知器类型。根据通知器的类型，你可以使用默认收件人或覆盖收件人。例如，如果你有 Slack 通知器，你可以更新通知发送的频道。你可以通过单击添加收件人来添加其他通知。

通过 YAML 配置通知

在 notification 中，你需要提供以下信息：

• Recipients：接收通知的通知器/收件人的列表。
  • Notifier：通知器的 ID。你可以先找到通知器，并选择在 API 中查看来获取 ID。
  • Recipient：根据通知器的类型，你可以使用“默认收件人”，或使用不同的收件人来覆盖默认收件人。例如，在配置 slack 通知器时，你选择一个频道作为默认收件人，但如果你想将通知发送到不同的频道，你也可以选择不同的收件人。
• Condition：发送通知的条件。
• Message（可选）：如果你想更改默认通知消息，你可以在 yaml 中进行编辑。注意：此选项在 UI 中不可用。

# 示例
stages:
  - name: Build something
    steps:
    - runScriptConfig:
        image: busybox
        shellScript: ls
notification:
  recipients:
  - # Recipient
    recipient: "#mychannel"
    # Notifier 的 ID
    notifier: "c-wdcsr:n-c9pg7"
  - recipient: "test@example.com"
    notifier: "c-wdcsr:n-lkrhd"
  # 选择发送通知的条件
  condition: ["Failed", "Success", "Changed"]
  # 覆盖默认消息（可选）
  message: "my-message"

触发器和触发器规则

配置流水线后，你可以使用不同的方法触发它：

• 手动：

  配置流水线后，你可以使用 Rancher UI 中的最新 CI 定义来触发构建。流水线执行被触发后，Rancher 会动态配置一个 Kubernetes pod 来运行你的 CI 任务，然后在完成后将该 Pod 移除。

• 自动：

  为流水线启用仓库后，Webhook 会自动添加到版本控制系统中。当项目用户通过推送代码、新建 PR 或创建标签与仓库交互时，版本控制系统会向 Rancher Server 发送一个 webhook，从而触发流水线执行。

  要使用此自动化，仓库需要 webhook 管理权限。因此，当用户进行身份验证并 fetch 仓库时，只会显示他们具有 webhook 管理权限的仓库。

你可以创建触发规则，从而对流水线配置中的流水线执行进行细粒度控制。触发规则有两种：

• Run this when：在触发器被显式触发时，此类规则将启动流水线、阶段或步骤。

• Do Not Run this when：当触发器被显式触发时，这类规则会跳过流水线、阶段或步骤。

如果所有条件都评估为 true，则执行流水线/阶段/步骤。否则将会跳过。跳过流水线时，不会执行任何流水线。如果一个阶段/步骤被跳过了，它会被认为是成功的，而且后续阶段/步骤会继续运行。

branch 条件支持通配符 (*) 扩展。

配置流水线触发器

1. 在左上角，单击 ☰ > 集群管理。

2. 转到要配置流水线的集群，然后单击 Explore。

3. 在顶部导航栏的下拉菜单中，选择要配置流水线的项目。

4. 在左侧导航栏中，单击 Legacy > 项目 > 流水线。

5. 在要管理触发器规则的仓库中，选择 ⋮ > 编辑配置。

6. 点击显示高级选项。

7. 在触发器中，配置规则以运行或跳过流水线。

   1. 单击添加规则。在值字段中，输入触发流水线的分支名称。

   2. 可选：添加更多触发构建的分支。

8. 单击完成。

配置阶段触发器

1. 在左上角，单击 ☰ > 集群管理。

2. 转到要配置流水线的集群，然后单击 Explore。

3. 在顶部导航栏的下拉菜单中，选择要配置流水线的项目。

4. 在左侧导航栏中，单击 Legacy > 项目 > 流水线。

5. 在要管理触发器规则的仓库中，选择 ⋮ > 编辑配置。

6. 找到要用于管理触发规则的阶段，单击该阶段的编辑图标。

7. 单击显示高级选项。

8. 在触发器中，配置规则以运行或跳过阶段。

   1. 单击添加规则。

   2. 选择触发阶段的类型并输入一个值。

      类型	值
      分支	触发阶段的分支名称。
      事件	触发阶段的事件类型。可选值为 Push，Pull Request 和 Tag。

9. 单击保存。

配置步骤触发器

1. 在左上角，单击 ☰ > 集群管理。

2. 转到要配置流水线的集群，然后单击 Explore。

3. 在顶部导航栏的下拉菜单中，选择要配置流水线的项目。

4. 在左侧导航栏中，单击 Legacy > 项目 > 流水线。

5. 在要管理触发器规则的仓库中，选择 ⋮ > 编辑配置。

6. 找到要用于管理触发规则的步骤，单击该步骤的编辑图标。

7. 单击显示高级选项。

8. 在触发器中，配置规则以运行或跳过步骤。

   1. 单击添加规则。

   2. 选择触发步骤的类型并输入一个值。

      类型	值
      分支	触发步骤的分支名称。
      事件	触发步骤的事件类型。可选值为 Push，Pull Request 和 Tag。

9. 单击保存。

通过 YAML 配置触发器

# 示例
stages:
  - name: Build something
    # 阶段的条件
    when:
      branch: master
      event: [ push, pull_request ]
    # 多个步骤并发运行
    steps:
    - runScriptConfig:
        image: busybox
        shellScript: date -R
      # 步骤条件
      when:
        branch: [ master, dev ]
        event: push
# 流水线的分支条件
branch:
  include: [ master, feature/*]
  exclude: [ dev ]

环境变量

配置流水线时，某些步骤类型会允许你使用环境变量来配置步骤的脚本。

通过 UI 配置环境变量

1. 在左上角，单击 ☰ > 集群管理。
2. 转到要配置流水线的集群，然后单击 Explore。
3. 在顶部导航栏的下拉菜单中，选择要配置流水线的项目。
4. 在左侧导航栏中，单击 Legacy > 项目 > 流水线。
5. 找到要编辑构建触发器的流水线，然后选择 ⋮ > 编辑配置。
6. 在其中一个阶段中，找到要为其添加环境变量的步骤，然后单击编辑图标。
7. 单击显示高级选项。
8. 单击添加变量，然后在出现的字段中输入键和值。根据需要添加更多的变量。
9. 将你的环境变量添加到脚本或文件中。
10. 单击保存。

通过 YAML 配置环境变量

# 示例
stages:
  - name: Build something
    steps:
    - runScriptConfig:
        image: busybox
        shellScript: echo ${FIRST_KEY} && echo ${SECOND_KEY}
      env:
        FIRST_KEY: VALUE
        SECOND_KEY: VALUE2

密文

如果你需要在流水线脚本中使用安全敏感信息（如密码），你可以使用 Kubernetes 密文来传入这些信息。

先决条件

在与流水线相同的项目中创建一个密文，或者在运行流水线构建 pod 的命名空间中显式创建一个密文。

:::note

PR 事件中的密文传入是禁用的。

:::

通过 UI 配置密文

1. 在左上角，单击 ☰ > 集群管理。
2. 转到要配置流水线的集群，然后单击 Explore。
3. 在顶部导航栏的下拉菜单中，选择要配置流水线的项目。
4. 在左侧导航栏中，单击 Legacy > 项目 > 流水线。
5. 找到要编辑构建触发器的流水线，然后选择 ⋮ > 编辑配置。
6. 在其中一个阶段中，找到要使用密文的步骤，然后单击编辑图标。
7. 单击显示高级选项。
8. 单击使用密文添加。选择要使用的密文文件。然后选择密钥。或者，你也可以输入密钥的别名。
9. 单击保存。

通过 YAML 配置密文

# 示例
stages:
  - name: Build something
    steps:
    - runScriptConfig:
        image: busybox
        shellScript: echo ${ALIAS_ENV}
      # 来自项目密文的环境变量
      envFrom:
      - sourceName: my-secret
        sourceKey: secret-key
        targetKey: ALIAS_ENV

流水线变量替换参考

为了方便你的使用，我们提供了以下在流水线配置脚本中可以使用的变量。在流水线执行期间，这些变量会被元数据替换。你可以使用 ${VAR_NAME} 格式引用这些变量。

变量名称	描述
CICD_GIT_REPO_NAME	仓库名称（省略 GitHub 组织）。
CICD_GIT_URL	Git 仓库的 URL。
CICD_GIT_COMMIT	正在执行的 Git commit ID。
CICD_GIT_BRANCH	此事件的 Git 分支。
CICD_GIT_REF	此事件的 Git 参考规范。
CICD_GIT_TAG	Git 标签名称，在标签事件上设置。
CICD_EVENT	触发构建的事件（push、pull_request 或 tag）。
CICD_PIPELINE_ID	流水线的 Rancher ID。
CICD_EXECUTION_SEQUENCE	流水线的生成号（build number）。
CICD_EXECUTION_ID	{CICD_PIPELINE_ID}-{CICD_EXECUTION_SEQUENCE} 的组合。
CICD_REGISTRY	上一个发布镜像步骤的 Docker 镜像仓库地址，可在部署 YAML 步骤的 Kubernetes 清单文件中找到。
CICD_IMAGE	上一个发布镜像步骤构建的镜像的名称，可在 Deploy YAML 步骤的 Kubernetes 清单文件中找到。不包含镜像标签。 示例

全局流水线执行设置

配置版本控制提供商后，你可以在 Rancher 中全局配置流水线的几个执行选项。

更改流水线设置

:::note 先决条件：

由于流水线应用已被弃用并替换为 Fleet，因此在使用流水线之前，你需要打开旧版功能的功能开关。请注意，我们不再支持 Kubernetes 1.21+ 中的流水线。

1. 在左上角，单击 ☰ > 全局设置。
2. 单击功能开关。
3. 转到旧版应用 功能开关并单击 ⋮ > 激活。

:::

要编辑这些设置：

1. 在左上角，单击 ☰ > 集群管理。
2. 转到要配置流水线的集群，然后单击 Explore。
3. 在顶部导航栏的下拉菜单中，选择要配置流水线的项目。
4. 在左侧导航栏中，单击 Legacy > 项目 > 流水线。

• Executor 配额
• Executor 的资源配额
• 自定义 CA

Executor 配额

选择流水线 Executor 的最大数量。executor 配额 决定了项目中可以同时运行多少个构建。如果触发的构建数量超过配额，后续构建将排队并等待空缺。默认情况下，配额为 2。如果配置为 0 或更小的值，则表示删除配额限制。

Executor 的资源配额

为 Jenkins Agent 容器配置计算资源。当触发流水线执行时，会动态配置构建 pod 以运行你的 CI 任务。在底层，一个构建 pod 由一个 Jenkins Agent 容器和一个用于各个流水线步骤的容器组成。你可以为 pod 中的每个容器管理计算资源。

编辑内存预留、内存限制、CPU 预留或 CPU 限制，然后点击更新限制和预留。

要为流水线步骤容器配置计算资源：

你可以在 .rancher-pipeline.yml 文件中为流水线步骤容器配置计算资源。

在步骤中，你需要提供以下信息：

• CPU 预留 (CpuRequest)：对流水线步骤的容器的 CPU 请求。
• CPU 预留 (CpuRequest)：对流水线步骤的容器的 CPU 限制。
• 内存预留 (MemoryRequest)：对流水线步骤的容器的内存请求。
• 内存限制（MemoryLimit）：对流水线步骤的容器的内存限制。

# 示例
stages:
  - name: Build something
    steps:
    - runScriptConfig:
        image: busybox
        shellScript: ls
      cpuRequest: 100m
      cpuLimit: 1
      memoryRequest:100Mi
      memoryLimit: 1Gi
    - publishImageConfig:
        dockerfilePath: ./Dockerfile
        buildContext: .
        tag: repo/app:v1
      cpuRequest: 100m
      cpuLimit: 1
      memoryRequest:100Mi
      memoryLimit: 1Gi

:::note

Rancher 为流水线步骤设置了默认计算资源（构建和发布镜像和运行脚本步骤除外）。你可以通过指定计算资源来覆盖默认值。

:::

自定义 CA

如果你想将版本控制提供商与自定义/内部 CA 根证书一起使用，则需要将 CA 根证书添加到版本控制提供商的配置中，从而让流水线构建 pod 成功运行。

1. 单击编辑证书。

2. 粘贴 CA 根证书并单击保存 CA 证书。

结果：你现在可以使用流水线，而且新的 pod 将能够使用自签名证书。

流水线组件的持久化数据

默认情况下，内部 Docker 镜像仓库和 Minio 工作负载都使用临时卷。这是开箱即用的默认存储方式，能让测试变得更加便利。但如果运行 Docker 镜像仓库或 Minio 的节点出现故障，你将丢失构建镜像和构建日志。在大多数情况下，这不是太大的问题。如果你希望构建镜像和日志能够在节点故障中幸免于难，你可以让 Docker 镜像仓库和 Minio 使用持久卷。

有关为流水线设置持久存储的详细信息，请参阅此页面。

示例 rancher-pipeline.yml

如果你需要查看示例流水线配置文件，请参见此页面。