Skip to content

Latest commit

 

History

History
278 lines (196 loc) · 12.7 KB

workspaces.md

File metadata and controls

278 lines (196 loc) · 12.7 KB

工作区

概览

工作区允许Tasks定义一部分文件系统，然后通过TaskRuns在运行时提供。TaskRun可以通过多种方式来指定：使用只读的ConfigMap或Secret，已存在的PersistentVolumeClaim，由提供的VolumeClaimTemplate模版创建新的PersistentVolumeClaim，或则简单的emptyDir.

工作区与Volumes相似，除了它允许Task作者让用户和TaskRuns运行是决定使用哪一个存储类.

工作区可用于以下目的:

  • 存储输入或输出
  • 在Tasks之间分享数据
  • 挂载Secrets中的凭证
  • 挂载ConfigMaps中的配置
  • 挂载组织中的常用工具
  • 缓存工件来加速构建过程

Tasks和TaskRuns中的工作区（Workspaces）

Tasks为起步骤指明一个工作区存在于磁盘中，在运行时，TaskRun提供Volume明细来挂载到工作区中.

关注点的分离可以提供更多的灵活性，例如，隔离的TaskRun可以通过提供emptyDir卷来更快地挂载，然后在执行完成后自动清除. 在更复杂的系统中，TaskRun可能使用PersistentVolumeClaim提前准备好数据供Task处理。这两种场景可能使用同一个Task's及工作区，然后在TaskRun中根据情况来指定.

Pipelines和PipelineRuns中的工作区

Pipeline可以使用工作区来在属于它的Tasks之间共享存储。例如，Task可以克隆源代码仓储到一个工作区，然后另一个Task可以从工作区中编译代码。Pipeline's保证两个Tasks使用相同的工作区，更重要的时，采用正确的顺序来访问工作区.

PipelineRuns处理方式与TaskRuns一样 —— 它们提供特定的Volume信息来让每一个Pipeline使用工作区. PipelineRuns另外的职责是确保无论何种类型的Volume都可以在Tasks间安全和正确的共享.

配置工作区

本节描述如何在TaskRun中配置一个或多个工作区.

在Tasks中使用工作区

要在Task中配置一个或多个工作区,添加一个workspaces，并指定包含以下字段的列表:

  • name - (必须) 一个 唯一 的字符串标识，通过它可以引用此工作区
  • description - 描述此工作区的信息
  • readOnly - 定义Task是否可写入此工作区.
  • mountPath - 工作区挂载的磁盘位置，Steps中可通过此路径访问。路径相对于/workspace，如果未指定mountPath，将会默认为/workspace/<name>，<name>为工作区唯一的名称.

注意:

  • Task可以包含多个工作区.
  • readOnly Workspace将会通过read-only方式挂载，尝试写入只读工作区将导致TaskRuns失败.
  • mountPath可以是绝对路径或相对路径，绝对路径必须以/开始，相对路径开始于目录名称，例如， mountPath 为 "/foobar"是绝对路径，导出的工作区路径为/foobar，但是mountPath 为 "foobar"是相对路径，其实际路径为/workspace/foobar.

以下Task示例包含一个名称为messages的工作区，Task将消息写入此位置:

spec:
  steps:
  - name: write-message
    image: ubuntu
    script: |
      #!/usr/bin/env bash
      set -xe
      echo hello! > $(workspaces.messages.path)/message
  workspaces:
  - name: messages
    description: The folder where we write the message to
    mountPath: /custom/path/relative/to/root

在TaskRuns中使用工作区变量

Tasks中可通过以下变量获取工作区信息:

  • $(workspaces.<name>.path) - 工作区的路径，<name>是工作区的名称.
  • $(workspaces.<name>.volume)- 工作区的Volume，<name>是工作区的名称.

映射Tasks中的工作区到TaskRuns

TaskRun在执行包含工作区列表的Task时，必须将工作区绑定到真实的物理Volumes，由此，TaskRun包含自己的workspaces列表，每一项包含以下字段:

  • name - (必须) 工作区的名称
  • subPath - 可选的Volume中的子路径，这里面的数据将会挂载到Workspace

项中也必须包含一个VolumeSource,参考与工作区一起使用 VolumeSources 获取更多信息.

注意:

  • 在TaskRun执行之前，subPath 必须 存在在卷中，否则TaskRun将会执行失败.
  • 工作区必须在执行与Task关联的TaskRun之前有效，否则TaskRun将会失败.

使用工作区的TaskRun定义示例

以下示例展示了如何在TaskRun中指定工作区,有关更多信息, 参考 在TaskRun中的工作区.

在以下示例中，存在一个名称为PersistentVolumeClaim的持久化存储声明，它被用于名称为myworkspace的工作区中，它只导出PVC中的my-subdir子目录:

workspaces:
- name: myworkspace
  persistentVolumeClaim:
    claimName: mypvc
  subPath: my-subdir

在以下示例中，提供一个emptyDir给任务的名称为myworkspace的工作区:

workspaces:
- name: myworkspace
  emptyDir: {}

以下示例中，为Task中名称为myworkspace的工作区指定一个名称为my-configmap的配置映射:

workspaces:
- name: myworkspace
  configmap:
    name: my-configmap

以下示例，为Task中名称为myworkspace的工作区指定一个名称为my-secret的密文:

workspaces:
- name: myworkspace
  secret:
    secretName: my-secret

有关更深入的示例，请参考workspace.yaml.

在Pipelines中使用工作区

独立的Tasks定义其运行所需工作区，Pipeline决定需要在其Tasks之间共享的工作区。要定义共享的工作区，你必须在Pipeline中定义以下信息:

  • 需要由PipelineRuns提供的工作区列表，使用workspaces字段定义工作区列表，列表中每一项具有唯一的名称.
  • 映射Pipeline与Task中工作区名称的映射.

以下示例定义了一个具有一个工作区的Pipeline，名称为pipeline-ws1.此工作区绑定到了两个Tasks —— 第一个gen-code任务作为输出工作区，然后作为第二个commit任务的src 工作区. 如果PipelineRun提供了PersistentVolumeClaim作为工作区，则可在Task之间共享数据.

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"
      workspaces:
        - name: src
          workspace: pipeline-ws1
      runAfter:
        - use-ws-from-pipeline # 重要: 实现执行use-ws-from-pipeline任务来写入数据

在Pipeline中指定工作区顺序

在Tasks之间共享一个工作区需要你定义这些Tasks访问工作区的顺序，因为不同的存储类具有不同的并发读写的限制. 例如，PersistentVolumeClaim可能只允许一个Task写入一次.

警告: 你 必须 确保顺序的正确性，不正确的顺序可能导致死锁，比如在多个Task Pods同时尝试挂载一个PersistentVolumeClaim来在同一时间写入时，这将导致Tasks超时.

要定义顺序，在Pipeline定义中使用runAfter字段，更多信息，参见runAfter 文档.

在PipelineRuns中指定工作区

要使用PipelineRun运行一个包含工作区的Pipeline，必须先将工作区绑定到真实的物理卷，这可以通过PipelineRun workspaces字段来设置工作区列表，列表中每一项包含以下字段:

  • name - (必须) Pipeline中定义的工作区名称.
  • subPath - (可选) 卷中的子路径，该路径中存储工作区需要使用的数据，该路径必须存在，否则TaskRun将执行失败.

项中必须包含一种VolumeSource，参考与工作区一起使用VolumeSources.

注意: 如果Pipeline中定义的工作区，在PipelineRun中未绑定，PipelineRun将会失败.

使用工作区的PipelineRun定义示例

以下示例阐述了如何在PipelineRuns中指定工作区，更深入的示例请参考PipelineRun中的工作区 YAML 示例.

在以下示例中，存在一个名称为mypvc的PersistentVolumeClaim，用于名称为myworkspace的工作区，它只导出了mypvc中的my-subdir子路径:

workspaces:
- name: myworkspace
  persistentVolumeClaim:
    claimName: mypvc
  subPath: my-subdir

以下示例中, 将名称为my-configmap的配置映射用于Pipeline中定义的名称为myworkspace的工作区中:

workspaces:
- name: myworkspace
  configmap:
    name: my-configmap

以下示例中, 将名称为my-secret的密文用于Pipeline中定义的名称为myworkspace的工作区中:

workspaces:
- name: myworkspace
  secret:
    secretName: my-secret

在Workspaces中指定VolumeSources

你在每一个工作区中可使用一种类型的VolumeSource. 每一种类型具有不同的配置项Workspaces 支持以下字段:

emptyDir

emptyDir 字段指向emptyDir 卷 ，它存储TaskRun运行的临时数据. emptyDir 卷不 适合于在管道任务之间共享数据. 但是，它适用于在TaskRuns内部步骤之间共享数据.

persistentVolumeClaim

persistentVolumeClaim指向persistentVolumeClaim卷. PersistentVolumeClaim卷是在Pipeline中Tasks之间共享数据的好选择.

volumeClaimTemplate

volumeClaimTemplate是persistentVolumeClaim卷的模版, 为每一个PipelineRun或者TaskRun创建，由PipelineRun或TaskRun从模版创建的PVC，将在PipelineRun或TaskRun删除后被删除.

当需要在运行PipelineRun或TaskRun时共享数据时，volumeClaimTemplate卷是好的选择.

configMap

configMap指向configMap卷. 使用configMap作为工作区，具有以下限制:

  • configMap卷总是只读，步骤不能进行写入.
  • configMap指定的配置映射必须在TaskRun运行时存在.
  • configMaps最大不超过1MB.

secret

secret字段指向secret卷. 使用secret卷作为工作区，具有以下限制:

  • secret卷总是只读，步骤不能进行写入.
  • secret指定的密文必须在TaskRun运行时存在.
  • secret最大不超过1MB.

如果你需要一个目前尚未存在的VolumeSource类型, 可在github上提交需求 或者 pull request.

更多示例

以下包含有关配置工作区的更详细的示例: