为 Selector 添加自定义 Task 镜像

本指南说明如何为 UI Task 表单中的 image 参数配置 selector 选项,涵盖两种场景:

  • 为 hub Tasks 添加镜像
  • 为 您自己的 namespace Tasks 添加镜像

功能概览

  • 每个 selector 选项都来自一个 ConfigMap,其中 data.name 为标签,data.image 为值。
  • Task 专用标签(例如 catalog.tekton.dev/tool-image-python)用于让 UI 将 ConfigMaps 匹配到正确的 Task 参数。
  • UI 使用 Task 注解中指定的 namespace(例如 kube-public),并通过 Task 描述符中定义的 label selector 查询该 namespace,然后使用结果渲染 selector。

使用场景

  • 为 Task selector 添加一个自定义的 registry mirror 镜像。
  • 在现有 selector 选项之外引入一个新的 runtime minor 版本。
  • 为自定义 Task 提供一个加固后的镜像选项。

前提条件

  • 已安装 Tekton Pipelines。
  • 您可以在 kube-public 中创建 ConfigMaps。
  • 您可以在目标 Task 上设置 style.tekton.dev/descriptors(Hub Tasks 已经提供;自定义 Tasks 需要您自行添加)。

场景 A:为 Hub Task selector 添加镜像

当您要扩展 Hub Task 的 selector 时,请使用此流程。

1. 从 Task 描述符中查找 label selector

在 Task 上定位 style.tekton.dev/descriptors 注解,并找到其 path 指向 image 参数的条目。

以 urn:alm:descriptor:expression:props.options:api 结尾的 descriptor 包含一个 labelSelector=... 查询;其中的 label key 必须存在于您的 ConfigMap 上。

在以下示例中,您需要在 kube-public namespace 中创建一个带有 catalog.tekton.dev/tool-image-python 标签的 ConfigMap。

kind: Task
metadata:
  name: python
  labels:
    app.kubernetes.io/version: "0.1"
  annotations:
    style.tekton.dev/descriptors: |
      - path: params.PYTHON_IMAGE
        x-descriptors:
          ...
          - urn:alm:descriptor:expression:props.options:api:/kubernetes/${context.cluster}/api/v1/namespaces/kube-public/configmaps?labelSelector=catalog.tekton.dev%2Ftool-image-python
          ...

有关 style.tekton.dev/descriptors 的更多信息,请参见 How to Configure Dynamic Forms。

2. 在 kube-public 中创建一个 ConfigMap

使用该 label key 创建一个 ConfigMap。

默认 Tasks 会随附带带有 catalog.tekton.dev/source: system 标签的 ConfigMaps,用于标识平台提供的条目。请勿修改或删除这些条目,且您的自定义 ConfigMaps 不应包含此标签。

apiVersion: v1
kind: ConfigMap
metadata:
  name: tekton-task-python-custom
  namespace: kube-public
  labels:
    catalog.tekton.dev/tool-image-python: "3.10"
data:
  name: "Python 3.10"
  image: "registry.example.com/tekton/python:3.10"

3. 应用并验证

kubectl apply -f tekton-task-python-custom.yaml
# configmap/tekton-task-python-custom created

kubectl -n kube-public get configmap -l catalog.tekton.dev/tool-image-python=3.10
# NAME                             DATA   AGE
# tekton-task-python-custom        2      15s

打开 Task 表单;selector 现在应包含 Python 3.10,并将 image 设置为 registry.example.com/tekton/python:3.10。

场景 B:为您自己的 Task selector 添加镜像

当您可以控制 Task 定义,并且需要同时配置 descriptors 和 ConfigMaps 时,请使用此流程。

1. 在 Task 上配置 style.tekton.dev/descriptors

image selector 的示例 Task 描述符:

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: python
  labels:
    app.kubernetes.io/version: "0.1"
  annotations:
    style.tekton.dev/descriptors: |
      - path: params.PYTHON_IMAGE
        x-descriptors:
          - urn:alm:descriptor:label:en:PYTHON_IMAGE
          - urn:alm:descriptor:description:en:The used Python image.
          - urn:alm:descriptor:com.tectonic.ui:select:image
          - urn:alm:descriptor:expression:props.options:api:/kubernetes/${context.cluster}/api/v1/namespaces/kube-public/configmaps?labelSelector=catalog.tekton.dev%2Ftool-image-python-custom
          - urn:alm:descriptor:props:select:allowCreate
          - urn:alm:descriptor:expression:props.options:path:items
          - urn:alm:descriptor:expression:props.options:label:path:data.name
          - urn:alm:descriptor:expression:props.options:value:path:data.image
          - urn:alm:descriptor:com.tectonic.ui:validation:required
spec:
  params:
    - name: PYTHON_IMAGE
      description: Image used for Python steps.
      type: string
  steps:
    - name: python-script
      image: $(params.PYTHON_IMAGE)
      script: |
        #!/bin/sh
        # Define your task script

Descriptor 条目及其含义:

Descriptor 条目作用示例备注
path指向作为 selector 渲染的参数。params.PYTHON_IMAGE
urn:alm:descriptor:label:en表单中显示的英文字段标签。PYTHON_IMAGE
urn:alm:descriptor:description:en字段的英文帮助文本。The used Python image.
urn:alm:descriptor:com.tectonic.ui:select:image将该字段渲染为 image selector。无需更改。
urn:alm:descriptor:expression:props.options:api获取 selector 选项的 API(namespace + label selector)。/kubernetes/${context.cluster}/api/v1/namespaces/kube-public/configmaps?labelSelector=catalog.tekton.dev%2Ftool-image-python-custom在此示例中,获取 kube-public 中带有 catalog.tekton.dev/tool-image-python-custom 标签的 ConfigMaps。
urn:alm:descriptor:props:select:allowCreate除 selector 选项外,还允许手动输入。
urn:alm:descriptor:expression:props.options:path指向 API 响应中的列表路径。urn:alm:descriptor:expression:props.options:path:items在此示例中使用的是 List API,因此取值来自 items。
urn:alm:descriptor:expression:props.options:label:path从条目中读取 selector 显示文本。urn:alm:descriptor:expression:props.options:label:path:data.name在此示例中,取值来自 ConfigMap 的 data.name。
urn:alm:descriptor:expression:props.options:value:path从条目中读取 selector 值(image)。urn:alm:descriptor:expression:props.options:value:path:data.image在此示例中,取值来自 ConfigMap 的 data.image。
urn:alm:descriptor:com.tectonic.ui:validation:required将该字段标记为必填。

有关 style.tekton.dev/descriptors 的更多信息,请参见 How to Configure Dynamic Forms。

2. 在 kube-public 中创建匹配的 ConfigMap

使用与描述符查询相同的 label key。对于自定义 Tasks,建议使用不会与默认 Task selector 冲突的 label key,以避免在 Hub Tasks 中意外显示。

默认 Tasks 会随附带带有 catalog.tekton.dev/source: system 标签的 ConfigMaps,用于标识平台提供的条目。请勿修改或删除这些条目,且您的自定义 ConfigMaps 不应包含此标签。

apiVersion: v1
kind: ConfigMap
metadata:
  name: custom-task-python-3-13
  namespace: kube-public
  labels:
    catalog.tekton.dev/tool-image-python-custom: "3.13-team"
data:
  name: "Python 3.13 (Team Edition)"
  image: "registry.example.com/internal/python:3.13"

您也可以将 ConfigMap 放在您偏好的其他任何 namespace 中;只需确保 ConfigMap 的 namespace 与 Task 的 style.tekton.dev/descriptors 注解中指定的 namespace 相同即可。 例如,您可以将 Task 的注解设置为如下示例,请将 <NAMESPACE> 替换为您的 namespace。

kind: Task
metadata:
  name: python
  labels:
    app.kubernetes.io/version: "0.1"
  annotations:
    # replace <NAMESPACE> with your namespace
    style.tekton.dev/descriptors: |
      - path: params.PYTHON_IMAGE
        x-descriptors:
          ...
          - urn:alm:descriptor:expression:props.options:api:/kubernetes/${context.cluster}/api/v1/namespaces/<NAMESPACE>/configmaps?labelSelector=catalog.tekton.dev%2Ftool-image-python-custom
          ...

3. 应用并验证

kubectl apply -f custom-task-python-3-13.yaml
# configmap/custom-task-python-3-13 created

kubectl -n kube-public get configmap -l catalog.tekton.dev/tool-image-python-custom=3.13-team
# NAME                             DATA   AGE
# custom-task-python-3-13          2      15s

打开您的 Task 表单;selector 应列出 Python 3.13 (Team Edition),并将 image 设置为 registry.example.com/internal/python:3.13。

维护建议

  • 通过编辑并重新应用其 ConfigMap 来更新自定义选项。
  • 删除某个选项时,只删除您自己的自定义 ConfigMap;保留任何带有 catalog.tekton.dev/source: system 的 ConfigMap 不变。