Skip to content

Commit 0e097f9

Browse files
author
edge-katanomi-app2[bot]
committed
📚 Sync docs from alaudadevops/tektoncd-operator on bee9862d3c9626e469487a24c13f31866f280a1c
Source: docs: [DEVOPS-42788] add docs for custom task images (#970) Author: yzc Ref: refs/heads/main Commit: bee9862d3c9626e469487a24c13f31866f280a1c This commit automatically syncs documentation changes from the source-docs repository. 🔗 View source commit: https://github.com/alaudadevops/tektoncd-operator/commit/bee9862d3c9626e469487a24c13f31866f280a1c 🤖 Synced on 2025-12-10 16:16:24 UTC
1 parent 4a0aa40 commit 0e097f9

File tree

3 files changed

+233
-72
lines changed

3 files changed

+233
-72
lines changed

‎.github/SYNC_INFO.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
# Documentation Sync Information
22

3-
- **Last synced**: 2025-12-10 09:54:35 UTC
3+
- **Last synced**: 2025-12-10 16:16:24 UTC
44
- **Source repository**: alaudadevops/tektoncd-operator
5-
- **Source commit**: [30fd2af0b51db4a0de2f7795a79c288ac83f0077](https://github.com/alaudadevops/tektoncd-operator/commit/30fd2af0b51db4a0de2f7795a79c288ac83f0077)
5+
- **Source commit**: [bee9862d3c9626e469487a24c13f31866f280a1c](https://github.com/alaudadevops/tektoncd-operator/commit/bee9862d3c9626e469487a24c13f31866f280a1c)
66
- **Triggered by**: edge-katanomi-app2[bot]
7-
- **Workflow run**: [#109](https://github.com/alaudadevops/tektoncd-operator/actions/runs/20094469751)
7+
- **Workflow run**: [#110](https://github.com/alaudadevops/tektoncd-operator/actions/runs/20105423471)
88

99
## Files synced:
1010
- docs/

‎docs/en/pipelines/how_to/add-custom-task-images-to-selector.mdx‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
---
2+
weight: 12
3+
i18n:
4+
title:
5+
en: Add Custom Task Images to Selector
6+
zh: 为 Task 镜像 selector 添加自定义镜像
7+
title: Add Custom Task Images to Selector
8+
---
9+
10+
# Add Custom Task Images to Selector
11+
12+
This guide explains how to configure selector options for the image parameter in the UI `Task` form, covering two scenarios:
13+
14+
- Adding images for **hub Tasks**
15+
- Adding images for **your own namespace Tasks**.
16+
17+
## Feature Overview
18+
19+
- Each selector option comes from a `ConfigMap` with `data.name` (label) and `data.image` (value).
20+
- Task-specific labels (for example, `catalog.tekton.dev/tool-image-python`) make the UI match `ConfigMaps` to the right
21+
`Task` parameter.
22+
- The UI queries the namespace specified in the `Task` annotation (for example, `kube-public`) using the label selector
23+
defined in the `Task` descriptor, then renders the selector with the results.
24+
25+
## Use Cases
26+
27+
- Add an customize registry mirror image for a `Task` selector.
28+
- Introduce a new runtime minor alongside existing selector options.
29+
- Provide a hardened image option for a custom `Task`.
30+
31+
## Prerequisites
32+
33+
- Tekton Pipelines is installed.
34+
- You can create `ConfigMaps` in `kube-public`.
35+
- You can set `style.tekton.dev/descriptors` on the target `Task` (`Hub Tasks` already provide it; custom `Tasks` need you to
36+
add it).
37+
38+
## Scenario A: Add images to a Hub Task selector
39+
40+
Use this path when extending the selector of a `Hub Task`.
41+
42+
### 1. Find the label selector from the Task descriptor
43+
44+
Locate the `style.tekton.dev/descriptors` annotation on the `Task` and find the entry whose `path` points to the image
45+
parameter.
46+
47+
The descriptor ending with `urn:alm:descriptor:expression:props.options:api` includes a `labelSelector=...` query; the
48+
label key there must be present on your `ConfigMap`.
49+
50+
In the following example, you need to create a `ConfigMap` with the `catalog.tekton.dev/tool-image-python` label in the
51+
`kube-public` namespace.
52+
53+
```yaml
54+
kind: Task
55+
metadata:
56+
name: python
57+
labels:
58+
app.kubernetes.io/version: "0.1"
59+
annotations:
60+
style.tekton.dev/descriptors: |
61+
- path: params.PYTHON_IMAGE
62+
x-descriptors:
63+
...
64+
- urn:alm:descriptor:expression:props.options:api:/kubernetes/${context.cluster}/api/v1/namespaces/kube-public/configmaps?labelSelector=catalog.tekton.dev%2Ftool-image-python
65+
...
66+
```
67+
68+
For more information of `style.tekton.dev/descriptors`, see [How to Configure Dynamic Forms](./configure_dynamic_forms).
69+
70+
### 2. Create a ConfigMap in kube-public
71+
72+
Create a `ConfigMap` using that label key.
73+
74+
> Default Tasks ship `ConfigMaps` labeled `catalog.tekton.dev/source: system` to indicate platform-provided entries. Do not modify or delete those, and your custom `ConfigMaps` should not include this label.
75+
76+
```yaml
77+
apiVersion: v1
78+
kind: ConfigMap
79+
metadata:
80+
name: tekton-task-python-custom
81+
namespace: kube-public
82+
labels:
83+
catalog.tekton.dev/tool-image-python: "3.10"
84+
data:
85+
name: "Python 3.10"
86+
image: "registry.example.com/tekton/python:3.10"
87+
```
88+
89+
### 3. Apply and verify
90+
91+
```bash
92+
kubectl apply -f tekton-task-python-custom.yaml
93+
# configmap/tekton-task-python-custom created
94+
95+
kubectl -n kube-public get configmap -l catalog.tekton.dev/tool-image-python=3.10
96+
# NAME DATA AGE
97+
# tekton-task-python-custom 2 15s
98+
```
99+
100+
Open the Task form; the selector should now include `Python 3.10` and set the image to
101+
`registry.example.com/tekton/python:3.10`.
102+
103+
## Scenario B: Add images to your own Task selector
104+
105+
Use this path when you control the `Task` definition and need to configure descriptors plus `ConfigMaps`.
106+
107+
### 1. Configure `style.tekton.dev/descriptors` on the Task
108+
109+
Example `Task` descriptor for an image selector:
110+
111+
```yaml
112+
apiVersion: tekton.dev/v1
113+
kind: Task
114+
metadata:
115+
name: python
116+
labels:
117+
app.kubernetes.io/version: "0.1"
118+
annotations:
119+
style.tekton.dev/descriptors: |
120+
- path: params.PYTHON_IMAGE
121+
x-descriptors:
122+
- urn:alm:descriptor:label:en:PYTHON_IMAGE
123+
- urn:alm:descriptor:description:en:The used Python image.
124+
- urn:alm:descriptor:com.tectonic.ui:select:image
125+
- urn:alm:descriptor:expression:props.options:api:/kubernetes/${context.cluster}/api/v1/namespaces/kube-public/configmaps?labelSelector=catalog.tekton.dev%2Ftool-image-python-custom
126+
- urn:alm:descriptor:props:select:allowCreate
127+
- urn:alm:descriptor:expression:props.options:path:items
128+
- urn:alm:descriptor:expression:props.options:label:path:data.name
129+
- urn:alm:descriptor:expression:props.options:value:path:data.image
130+
- urn:alm:descriptor:com.tectonic.ui:validation:required
131+
spec:
132+
params:
133+
- name: PYTHON_IMAGE
134+
description: Image used for Python steps.
135+
type: string
136+
```
137+
138+
Descriptor items and meanings:
139+
140+
| Descriptor entry | Purpose | Example | Remark |
141+
|----------------------------------------------------------|-------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|
142+
| `path` | Points to the parameter rendered as a selector. | `params.PYTHON_IMAGE` | |
143+
| `urn:alm:descriptor:label:en` | English field label shown in the form. | `PYTHON_IMAGE` | |
144+
| `urn:alm:descriptor:description:en` | English help text for the field. | `The used Python image.` | |
145+
| `urn:alm:descriptor:com.tectonic.ui:select:image` | Renders the field as an image selector. | | No change needed. |
146+
| `urn:alm:descriptor:expression:props.options:api` | API to fetch selector options (namespace + label selector). | `/kubernetes/${context.cluster}/api/v1/namespaces/kube-public/configmaps?labelSelector=catalog.tekton.dev%2Ftool-image-python-custom` | In the example, fetches ConfigMaps in `kube-public` with label `catalog.tekton.dev/tool-image-python-custom`. |
147+
| `urn:alm:descriptor:props:select:allowCreate` | Allows manual input in addition to selector options. | | |
148+
| `urn:alm:descriptor:expression:props.options:path` | Points to the list path in the API response. | `urn:alm:descriptor:expression:props.options:path:items` | In the example, the List API is used, so the values are taken from `items`. |
149+
| `urn:alm:descriptor:expression:props.options:label:path` | Reads selector display text from the item. | `urn:alm:descriptor:expression:props.options:label:path:data.name` | In the example, the value is taken from `data.name` of the `ConfigMap`. |
150+
| `urn:alm:descriptor:expression:props.options:value:path` | Reads selector value (image) from the item. | `urn:alm:descriptor:expression:props.options:value:path:data.image` | In the example, the value is taken from `data.image` of the `ConfigMap`. |
151+
| `urn:alm:descriptor:com.tectonic.ui:validation:required` | Marks the field as required. | | |
152+
153+
For more information of `style.tekton.dev/descriptors`, see [How to Configure Dynamic Forms](./configure_dynamic_forms).
154+
155+
### 2. Create a matching ConfigMap in kube-public
156+
157+
Use the same label key that your descriptor queries. For custom `Tasks`, prefer a label key that does not conflict with
158+
default `Task` selectors to avoid accidental display in `Hub Tasks`.
159+
160+
> Default Tasks ship `ConfigMaps` labeled `catalog.tekton.dev/source: system` to indicate platform-provided entries. Do not modify or delete those, and your custom `ConfigMaps` should not include this label.
161+
162+
```yaml
163+
apiVersion: v1
164+
kind: ConfigMap
165+
metadata:
166+
name: custom-task-python-3-13
167+
namespace: kube-public
168+
labels:
169+
catalog.tekton.dev/tool-image-python-custom: "3.13-team"
170+
data:
171+
name: "Python 3.13 (Team Edition)"
172+
image: "registry.example.com/internal/python:3.13"
173+
```
174+
175+
You can also place the `ConfigMap` in any other namespace you prefer; you just need to make sure that the `ConfigMap`'s namespace is the same as the namespace specified in the `Task`'s `style.tekton.dev/descriptors` annotation.
176+
For example, you can set the `Task`'s annotation as in the example below, please replace `<NAMESPACE>` with your namespace.
177+
178+
```yaml
179+
kind: Task
180+
metadata:
181+
name: python
182+
labels:
183+
app.kubernetes.io/version: "0.1"
184+
annotations:
185+
# replace <NAMESPACE> with your namespace
186+
style.tekton.dev/descriptors: |
187+
- path: params.PYTHON_IMAGE
188+
x-descriptors:
189+
...
190+
- urn:alm:descriptor:expression:props.options:api:/kubernetes/${context.cluster}/api/v1/namespaces/<NAMESPACE>/configmaps?labelSelector=catalog.tekton.dev%2Ftool-image-python-custom
191+
...
192+
```
193+
194+
### 3. Apply and validate
195+
196+
```bash
197+
kubectl apply -f custom-task-python-3-13.yaml
198+
# configmap/custom-task-python-3-13 created
199+
200+
kubectl -n kube-public get configmap -l catalog.tekton.dev/tool-image-python-custom=3.13-team
201+
# NAME DATA AGE
202+
# custom-task-python-3-13 2 15s
203+
```
204+
205+
Open your `Task` form; the selector should list `Python 3.13 (Team Edition)` and set the image to
206+
`registry.example.com/internal/python:3.13`.
207+
208+
## Maintenance tips
209+
210+
- Update a custom option by editing and re-applying its `ConfigMap`.
211+
- Retire an option by deleting only your custom `ConfigMap`; leave any `ConfigMap` with `catalog.tekton.dev/source: system`
212+
untouched.

‎docs/en/tutorials/prepare/discover_tool_image.mdx‎

Lines changed: 18 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -4,92 +4,41 @@ weight: 50
44

55
# Discover Tool Image
66

7-
This guide shows you how to discover tool images that help you run your Tekton Tasks and Pipelines.
8-
If you don't find the image you need, you can always build your own image and use it to run your Tasks and Pipelines.
7+
This guide shows you how to discover tool images that help you run your Tekton `Tasks` and `Pipelines`.
98

10-
## TL;DR
11-
12-
- Replace `<tekton-namespace>` with your Tekton namespace before running. Such as `tekton-pipelines`.
13-
- Replace `<image-name>` with your target image name. Such as `helm`.
14-
15-
Run the following command to get the image name:
16-
17-
```shell
18-
REG=$(kubectl -n kube-public get cm global-info -o jsonpath='{.data.registryAddress}')
19-
IMG=$(kubectl -n <tekton-namespace> get cm -l operator.tekton.dev/tool-image=<image-name> -o jsonpath='{.items[0].data.repository}:{.items[0].data.tag}')
20-
echo "${REG%/}/$IMG"
21-
```
22-
23-
- The second line selects array index 0 `(.items[0])`. If there are multiple matching ConfigMaps and index 0 isn't the one you want, change the index (e.g., `.items[1]`, `.items[2]`, …) or follow the step-by-step flow below to list and choose.
24-
- If `kube-public/global-info` doesn't exist (or lacks registryAddress), replace `REG` with your own registry, e.g.: `REG="registry.example.com"`.
9+
If you don't find the image you need, you can always build your own image and use it to run your `Tasks` and `Pipelines`.
10+
If you want to add custom tool images to `Task` image param selector for UI, you can refer to [Add Custom Task Images to Selector](../../pipelines/how_to/add-custom-task-images-to-selector).
2511

2612
## Prerequisites
2713

2814
- kubectl installed and configured to access the cluster.
29-
- Permissions to read ConfigMaps.
15+
- Permissions to read `ConfigMaps`.
3016

3117
## Step-by-Step Instructions
3218

33-
### Step 1: Get the registry
34-
35-
Try to read registryAddress from kube-public/global-info.
36-
37-
```shell
38-
REG=$(kubectl -n kube-public get cm global-info -o jsonpath='{.data.registryAddress}')
39-
```
40-
41-
If your cluster doesn't provide `kube-public/global-info`, you must replace REG with your registry (for example, `harbor.example.com`).
42-
43-
```shell
44-
REG="<your-registry>"
45-
```
46-
47-
### Step 2: List all candidate tool images in namespace
48-
49-
Replace `<tekton-namespace>` with your Tekton namespace before running. Such as `tekton-pipelines`.
19+
### Step 1: List available tool images
5020

51-
```shell
52-
kubectl -n <tekton-namespace> get cm -l operator.tekton.dev/tool-image -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.data.repository}:{.data.tag}{"\n"}{end}'
53-
```
54-
55-
This prints lines like:
56-
```
57-
tool-image-helm devops/tektoncd/hub/helm:3.18.0
58-
tool-image-foo devops/tektoncd/hub/foo:1.2.3
59-
tool-image-bar devops/tektoncd/hub/bar:2.3.4
60-
```
21+
Replace the namespace and label with the values you found.
6122

62-
If you only want a specific type image, you can use the following command.
63-
Replace `<image-name>` with your target image name. Such as `helm`.
23+
There are some default `ConfigMaps` in the `kube-public` namespace. You can use the label with `operator.tekton.dev/tool-image` to list all available tool images.
6424

6525
```shell
66-
kubectl -n <tekton-namespace> get cm -l operator.tekton.dev/tool-image=<image-name> -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.data.repository}:{.data.tag}{"\n"}{end}'
67-
```
68-
69-
This prints lines like:
70-
```
71-
tool-image-helm devops/tektoncd/hub/helm:3.18.0
72-
```
73-
74-
Select one of the images, and set `IMG` to the image name.
26+
kubectl -n <namespace> get configmap -l <label-selector> -o custom-columns=CONFIGMAP:.metadata.name,NAME:.data.name,IMAGE:.data.image
7527

76-
```shell
77-
IMG=devops/tektoncd/hub/helm:3.18.0
28+
# example
29+
kubectl -n kube-public get configmap -l operator.tekton.dev/tool-image=helm -o custom-columns=CONFIGMAP:.metadata.name,NAME:.data.name,IMAGE:.data.image
30+
# CONFIGMAP NAME IMAGE
31+
# catalog-tool-image-helm-3.18 Helm v3.18 registry.alauda.cn:60070/devops/tektoncd/hub/helm:v3.18
32+
# catalog-tool-image-helm-latest Helm Latest(v3.18) registry.alauda.cn:60070/devops/tektoncd/hub/helm:latest
7833
```
7934

80-
### Step 3: Print the final image name
81-
82-
```shell
83-
echo "${REG%/}/$IMG"
84-
```
35+
### Step 2: Choose the image
8536

86-
This prints like:
87-
```
88-
registry.example.com/devops/tektoncd/hub/helm:3.18.0
89-
```
37+
- Pick the row you need.
38+
- Use the `IMAGE` column directly in your `Task` or `Pipeline`.
9039

9140
## Troubleshooting
9241

9342
- **Empty output or errors**:
94-
- Ensure you can read ConfigMaps in namespaces.
95-
- Confirm `kube-public/global-info` exists and has a `registryAddress` key (or set `REG` manually as shown above).
43+
- Ensure you can read `ConfigMaps` in namespaces.
44+
- Confirm you used the namespace and label selector.

0 commit comments

Comments
 (0)