Skip to content

Latest commit

 

History

History
452 lines (371 loc) · 15.7 KB

pipelines.md

File metadata and controls

452 lines (371 loc) · 15.7 KB

管道

概览

Pipeline包含一系列排列为指定顺序的Tasks，通过它来执行持续集成流. 在Pipeline中的每一个Task作为Pod在你的Kubernetes集群中运行. 你可以配置多个条件来满足你的业务需求.

配置Pipeline

Pipeline定义支持以下字段:

  • 必须:
    • apiVersion - API版本, 例如 tekton.dev/v1beta1.
    • kind - 定义资源对象类型，固定为 Pipeline.
    • metadata - Pipeline对象相关的元数据，例如名称name.
    • spec - `Pipeline对象的配置信息, 它包括:
      • tasks - 指定Task，它构成了Pipeline的执行流程与功能.
  • 可选:
    • resources - alpha 指定组成Pipeline的Tasks所需要的 PipelineResources .
    • tasks:
      • resources.inputs / resource.outputs
      • runAfter - 指定一个Task应该在某个或多个其他Task之后执行.
      • retries - 当错误发生后，Task可重试的次数. 而不会取消任务执行.
      • conditions - 指定任务执行的条件,当评估结果为true时才执行任务.
      • timeout - Task失败前的超时时间.
    • results - 指定Pipeline执行结果存放的位置.
    • description - Pipeline对象的描述信息.

指定 Resources

Pipeline使用PipelineResources来为组成它的Task提供输入或存储输出，你可以通过spec下的resources字段来定义，其中的每一项资源中必须指定唯一的name及其type。例如:

spec:
  resources:
    - name: my-repo
      type: git
    - name: my-image
      type: image

指定 Workspaces

工作区允许你为Pipeline中每一个Task指定在其执行期间所需的一个或多个卷. 你可以通过workspaces字段指定一个或多个工作区. 例如:

spec:
  workspaces:
    - name: pipeline-ws1 # Pipeline中工作区的名称
  tasks:
    - name: use-ws-from-pipeline
      taskRef:
        name: gen-code # gen-code包含一个名称为`output`的工作区
      workspaces:
        - name: output
          workspace: pipeline-ws1
    - name: use-ws-again
      taskRef:
        name: commit # commit包含一个名称为`src`的工作区
      runAfter:
        - use-ws-from-pipeline # 重要: use-ws-from-pipeline任务首先需要写入工作区
      workspaces:
        - name: src
          workspace: pipeline-ws1

有关更多信息, 参考:

指定-Parameters

你可以指定需要在Pipeline执行时传递的全局参数，如编译标识或者制品名称. 参数通过PipelineRun传递给Pipeline，可替换Pipeline中每一个Task的模板值.

参数名称:

  • 必须只能使用字符或数字，及连字符(-)或下划线(_).
  • 必须以字母或下划线开始(_).

例如, fooIs-Bar_是有效的参数名称, 但 barIsBa$ 或者 0banana 无效.

每一个定义的参数包含一个type字段，它可以设置为array或者字符串. array可用于传递Pipeline中所需要的多个编译标识，如果未指定type字段，默认为string. 当应用实际的参数值时，将会验证type值. 参数的description及default字段是可选的.

以下示例展示了如何在Pipeline中使用Parameters.

以下Pipeline定义了一个输入参数，名称为context，然后传递值到Task，以便于设置Task中的pathToContext参数. 如果你设置了default字段，然后在调用Pipeline的PipelineRun中未设置值，那么将会使用此默认值.

注意: 输入参数值在整个Pipeline中可作为变量使用，通过变量替换的方式.

apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: pipeline-with-parameters
spec:
  params:
    - name: context
      type: string
      description: Path to context
      default: /some/where/or/other
  tasks:
    - name: build-skaffold-web
      taskRef:
        name: build-push
      params:
        - name: pathToDockerFile
          value: Dockerfile
        - name: pathToContext
          value: "$(params.context)"

以下PipelineRun提供了context参数的值:

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: pipelinerun-with-parameters
spec:
  pipelineRef:
    name: pipeline-with-parameters
  params:
    - name: "context"
      value: "/workspace/examples/microservices/leeroy-web"

添加 Tasks 到 Pipeline

Pipeline定义中必须引用至少一个Task. Pipeline中的每一个Task必须具有一个有效的name以及taskRef。例如:

tasks:
  - name: build-the-image
    taskRef:
      name: build-push

你可以使用PipelineResources作为Tasks的输入和输出。例如:

spec:
  tasks:
    - name: build-the-image
      taskRef:
        name: build-push
      resources:
        inputs:
          - name: workspace
            resource: my-repo
        outputs:
          - name: image
            resource: my-image

你也可以为任务提供参数:

spec:
  tasks:
    - name: build-skaffold-web
      taskRef:
        name: build-push
      params:
        - name: pathToDockerFile
          value: Dockerfile
        - name: pathToContext
          value: /workspace/examples/microservices/leeroy-web

使用 from 参数

如果Pipeline中的一个Task需要使用之前的Task的输出作为它的输入，可使用from参数来指定一个Tasks列表，指明这边任务必须在目标任务执行之前执行。当你的目标任务执行时，只有任务列表中最后一个Task输出的结果PipelineResource被使用。此输出PipelineResource的名称必须与目标Task输入PipelineResource名称一致.

在以下示例中，deploy-app Task使用build-app任务名称为my-image资源的输出作为其输入. 因此, build-app Task将会在deploy-app Task之前执行，而不管任务在Pipeline中的顺序.

- name: build-app
  taskRef:
    name: build-push
  resources:
    outputs:
      - name: image
        resource: my-image
- name: deploy-app
  taskRef:
    name: deploy-kubectl
  resources:
    inputs:
      - name: image
        resource: my-image
        from:
          - build-app

使用 runAfter 参数

如果你需要Pipeline中的任务按照指定的顺序执行，而没有需要通过from参数指定的依赖资源，可使用runAfter参数来指定任务需要在一个或多个其他Task之后执行.

在以下示例中，我们需要在构建之前先进行代码测试。由于构建任务不会使用test-app任务的任何输出，所以build-app任务使用runAfter来指定test-app必须在之前运行，而不管任务在Pipeline中的实际顺序.

- name: test-app
  taskRef:
    name: make-test
  resources:
    inputs:
      - name: workspace
        resource: my-repo
- name: build-app
  taskRef:
    name: kaniko-build
  runAfter:
    - test-app
  resources:
    inputs:
      - name: workspace
        resource: my-repo

使用 retries 参数

在Pipeline中的每一个Task，你可以指定Tekton在任务失败后可以自动重试的次数. 当Task失败了， 其关联的TaskRun将会设置成功 条件为False. retries参数命令Tekton在此条件发生时重试.

如果你知道Task在执行过程中可能会有些问题（例如，你可能知道有一些网络连接问题或者依赖丢失），那么你可以将retries参数值设置为大于0的数。如果你没有设置此参数，Tekton不会在Task失败时进行重试的尝试。.

在以下示例中，build-the-image Task将会在失败后重试一次，如果重试失败，Task执行将会失败.

tasks:
  - name: build-the-image
    retries: 1
    taskRef:
      name: build-push

指定执行条件 Conditions

有时你只需要在某些条件满足时才执行任务，condition字段允许你应用一系列的条件，这些条件在任务执行前运行，如果所有的条件评估为true，任务将会运行，如果其中任何一个条件返回false，任务将不会被执行。此时status.ConditionSucceeded被设置为ConditionCheckFailed, 不过，与其他任务失败不同的是，条件失败不会自动导致整个管道失败 -- 其它不依赖于此任务的任务(通过from或者runAfter)将会持续运行.

tasks:
  - name: conditional-task
    taskRef:
      name: build-push
    conditions:
      - conditionRef: my-condition
        params:
          - name: my-param
            value: my-value
        resources:
          - name: workspace
            resource: source-repo

在此示例中，my-condition引用一个条件自定义资源. build-push任务将会在条件评估为true时执行.

条件中的资源同样可以使用from 字段来使用之前任务的输出作为条件的输入资源. 就像Pipeline中的任务一样，通过from会影响任务执行顺序 -- 如果一个条件需要另外一个任务的输出，那么产生资源的任务将会首先被执行:

tasks:
  - name: first-create-file
    taskRef:
      name: create-file
    resources:
      outputs:
        - name: workspace
          resource: source-repo
  - name: then-check
    conditions:
      - conditionRef: "file-exists"
        resources:
          - name: workspace
            resource: source-repo
            from: [first-create-file]
    taskRef:
      name: echo-hello

配置失败超时时间

你可以通过Pipeline中的Task配置下的Timeout参数来设置执行Pipeline关联的PipelineRun中通过TaskRun来执行具体Task的超时时间。 超时时间值是一个Go语言的duration格式，可参考ParseDuration, 有效值为1h30m, 1h, 1m, 以及 60s.

注意: 如果你没有设置Timeout值，Tekton将使用PipelineRun超时替代.

在以下示例中，build-the-image Task任务配置的超时时间为90秒:

spec:
  tasks:
    - name: build-the-image
      taskRef:
        name: build-push
      Timeout: "0h1m30s"

在Task级别配置执行结果

任务执行后可以产出Results，你可以在Pipeline随后的Task中以参数的方式使用这些结果，通过变量替换, Tekton可推断Task的执行顺序，以便于在Task使用这些结果之前确保结果对应任务已被执行.

在以下示例中，previous-task-name Task任务结果作为bar-result公开:

params:
  - name: foo
    value: "$(tasks.previous-task-name.results.bar-result)"

请参考PipelineRun中的任务结果.

在Pipeline级别配置执行结果

你可以配置你的Pipeline来产出结果, 这些结果由管道中的Task所产生.

在以下示例中，Pipeline指定了一个results项，名称为sum，它是由second-add 任务所产生的.

  results:
    - name: sum
      description: the sum of all three operands
      value: $(tasks.second-add.results.sum)

有关示例，可参考PipelineRun中的结果.

配置Task执行顺序

你可以通过Pipeline来连接Task，所以他们的执行可以构成有向无环图(DAG). Pipeline中的每一个Task作为图中的一个节点，他们可以通过边连接起来，所以Pipeline可以处理完成而不会死循环.

这可通过使用:

例如, 如下的Pipeline定义：

- name: lint-repo
  taskRef:
    name: pylint
  resources:
    inputs:
      - name: workspace
        resource: my-repo
- name: test-app
  taskRef:
    name: make-test
  resources:
    inputs:
      - name: workspace
        resource: my-repo
- name: build-app
  taskRef:
    name: kaniko-build-app
  runAfter:
    - test-app
  resources:
    inputs:
      - name: workspace
        resource: my-repo
    outputs:
      - name: image
        resource: my-app-image
- name: build-frontend
  taskRef:
    name: kaniko-build-frontend
  runAfter:
    - test-app
  resources:
    inputs:
      - name: workspace
        resource: my-repo
    outputs:
      - name: image
        resource: my-frontend-image
- name: deploy-all
  taskRef:
    name: deploy-kubectl
  resources:
    inputs:
      - name: my-app-image
        resource: my-app-image
        from:
          - build-app
      - name: my-frontend-image
        resource: my-frontend-image
        from:
          - build-frontend

执行顺序图如下:

        |            |
        v            v
     test-app    lint-repo
    /        \
   v          v
build-app  build-frontend
   \          /
    v        v
    deploy-all

详细说明:

  1. lint-repo 和 test-app 任务 没有 from 或 runAfter 子句，他们将会被立即同时执行.
  2. 一旦 test-app 完成, build-app 和 build-frontend 任务将会同时开始，因为他们都有runAfter子句，并指向test-app任务.
  3. deploy-all 任务在build-app 和 build-frontend任务完成后执行，因为他会使用这两个任务的输出资源.
  4. 整个Pipeline将会在lint-repo 和 deploy-all任务完成时完成.

添加描述

description字段是可选字段，可通过此字段设置Pipeline的描述信息.

代码示例

为了更好地理解Pipelines, 可通过学习我们的示例.

除非另有说明，本页内容采用Creative Commons Attribution 4.0 License授权协议，示例代码采用Apache 2.0 License授权协议