Skip to content

Commit 6962118

Browse files
author
edge-katanomi-app2[bot]
committed
📚 Sync docs from alaudadevops/tektoncd-operator on 9b67af1066d87606e7c19632060d13f3aa7cb5de
Source: docs: move tep dev docs from sub repos (#721) Author: yzc Ref: refs/heads/main Commit: 9b67af1066d87606e7c19632060d13f3aa7cb5de This commit automatically syncs documentation changes from the source-docs repository. 🔗 View source commit: https://github.com/alaudadevops/tektoncd-operator/commit/9b67af1066d87606e7c19632060d13f3aa7cb5de 🤖 Synced on 2025-10-31 10:21:32 UTC
1 parent dc253f9 commit 6962118

File tree

18 files changed

+5262
-4
lines changed

18 files changed

+5262
-4
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-10-31 08:06:45 UTC
3+
- **Last synced**: 2025-10-31 10:21:31 UTC
44
- **Source repository**: alaudadevops/tektoncd-operator
5-
- **Source commit**: [008418e262fa3d4198fa49b2e601f08fa861f54a](https://github.com/alaudadevops/tektoncd-operator/commit/008418e262fa3d4198fa49b2e601f08fa861f54a)
5+
- **Source commit**: [9b67af1066d87606e7c19632060d13f3aa7cb5de](https://github.com/alaudadevops/tektoncd-operator/commit/9b67af1066d87606e7c19632060d13f3aa7cb5de)
66
- **Triggered by**: edge-katanomi-app2[bot]
7-
- **Workflow run**: [#90](https://github.com/alaudadevops/tektoncd-operator/actions/runs/18966544073)
7+
- **Workflow run**: [#91](https://github.com/alaudadevops/tektoncd-operator/actions/runs/18969631201)
88

99
## Files synced:
1010
- docs/

‎docs/en/development/catalog/convention.md‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
---
2+
weight: 10
3+
status: proposed
4+
title: Catalog Conventions
5+
creation-date: "2025-02-20"
6+
category: docs
7+
authors:
8+
- "@qingliu"
9+
---
10+
11+
# Catalog Conventions
12+
13+
## Task Conventions
14+
15+
### 1. Follow Community [Catalog](https://github.com/tektoncd/catalog) Conventions
16+
17+
Catalog Structure
18+
19+
1. Each resource follows the following structure
20+
21+
```
22+
./task/ 👈 the kind of the resource
23+
24+
/argocd 👈 definition file must have same name
25+
/0.1
26+
/OWNERS 👈 owners of this resource
27+
/README.md
28+
/DEVELOPMENT.md 👈 development guide
29+
/argocd.yaml 👈 the file name should match the resource name
30+
/samples/deploy-to-k8s.yaml
31+
/0.2/...
32+
33+
/golang-build
34+
/OWNERS
35+
/README.md
36+
/0.1
37+
/README.md
38+
/golang-build.yaml
39+
/samples/golang-build.yaml
40+
```
41+
42+
2. Resource YAML file includes following changes
43+
* Labels include the version of the resource.
44+
* Annotations include `minimum pipeline version` supported by the resource,
45+
`tags` associated with the resource and `displayName` of the resource
46+
47+
```yaml
48+
49+
labels:
50+
app.kubernetes.io/version: "0.1" 👈 Version of the resource, has to equal to the version in the file path, e.g. version == "0.1" in "example-task/0.1/example-task.yaml"
51+
52+
annotations:
53+
tekton.dev/pipelines.minVersion: "0.12.1" 👈 Min Version of pipeline resource is compatible
54+
tekton.dev/categories: CLI 👈 Comma separated list of categories
55+
tekton.dev/tags: "ansible, cli" 👈 Comma separated list of tags
56+
tekton.dev/displayName: "Ansible Tower Cli" 👈 displayName can be optional
57+
tekton.dev/platforms: "linux/amd64,linux/s390x" 👈 Comma separated list of platforms, can be optional
58+
tekton.dev/icon: data:image/svg+xml;base64,{{ base64 icon data }} 👈 The base64 encoded svg icon, can be optional
59+
60+
spec:
61+
description: |-
62+
ansible-tower-cli task simplifies
63+
workflow, jobs, manage users... 👈 Summary
64+
65+
Ansible Tower (formerly 'AWX') is a ...
66+
67+
```
68+
69+
**Note** : Categories are a generalized list and are maintained by Hub. To add new categories, please follow the procedure mentioned [here](https://github.com/tektoncd/hub/blob/main/docs/ADD_NEW_CATEGORY.md).
70+
71+
### 2. Use v1 Version of Task
72+
73+
Currently `tekton.dev/v1` is the default version, and this version does not have the `ClusterTask` resource type, therefore we recommend using the `v1` version of Task.
74+
75+
### 3. Specify Default Resources `computeResources` for Task
76+
77+
It is recommended that `Task` has a default `computeResources`, and users can override it through `TaskRun` if they need to adjust.
78+
79+
```yaml
80+
apiVersion: tekton.dev/v1
81+
kind: Task
82+
metadata:
83+
name: foo
84+
spec:
85+
steps:
86+
- name: sonar-properties-create
87+
computeResources:
88+
requests:
89+
cpu: "1"
90+
memory: "1Gi"
91+
limits:
92+
cpu: "2"
93+
memory: "2Gi"
94+
```
95+
96+
```yaml
97+
apiVersion: tekton.dev/v1
98+
kind: TaskRun
99+
metadata:
100+
name: foo-run
101+
spec:
102+
computeResources:
103+
requests:
104+
cpu: "2"
105+
memory: "2Gi"
106+
limits:
107+
cpu: "4"
108+
memory: "4Gi"
109+
```
110+
111+
### 4. Building Custom Images with Dependencies
112+
113+
If Tasks in the catalog depend on custom images, we need to provide `Dockerfile` and build pipelines in the catalog.
114+
115+
- Build environments are stored in the `images/{image-name}` directory
116+
- Image build pipeline orchestration files are stored in `.tekton/images/build-{image-name}.yaml`
117+
118+
#### Image Security
119+
120+
- For security considerations, it is recommended to create a `nonroot` user with ID `65532` as the default user when the image is finally executed.
121+
- It is also recommended to add `USER 65532` instead of `USER nonroot` in the `Dockerfile` to specify this user.
122+
- This is because when a Pod specifies `runAsNonRoot`, it cannot confirm that the user is non-root when using `USER nonroot`, which will result in a `CreateContainerConfigError`.
123+
124+
```dockerfile
125+
# Add a non-root user
126+
127+
# For Alpine images
128+
RUN adduser -u 65532 -h /home/nonroot -D nonroot -s /sbin/nologin
129+
130+
# For Debian, Ubuntu images
131+
RUN adduser --home /home/nonroot --uid 65532 nonroot --shell /usr/sbin/nologin --disabled-password --gecos ""
132+
133+
# Set the default user
134+
USER 65532
135+
```
136+
137+
#### Image Tags
138+
139+
If the image is custom, you can directly use the version number generated by `git-version` in the pipeline as the Tag.
140+
141+
If the image is customized based on a specific community version, it is recommended to add the community version number as a prefix in the Tag. For example, `v0.56.0-{version}`
142+
143+
In the pipeline, you can specify the image prefix by configuring the `tag-prefix` parameter.
144+
145+
#### Image Path
146+
147+
It is recommended to uniformly use `/devops/tektoncd/hub/` as the image path prefix for convenient image management in the future.
148+
149+
### 5. Not Recommended to Specify `runAsUser` in Task Definitions that Support User Custom Images
150+
151+
```yaml
152+
apiVersion: tekton.dev/v1
153+
kind: Task
154+
metadata:
155+
name: foo
156+
spec:
157+
steps:
158+
- name: bar
159+
securityContext:
160+
runAsNonRoot: true
161+
# runAsUser: 65532 # Not recommended to specify in Task
162+
```
163+
164+
This is because after specifying the `runAsUser` configuration in the `step` of a `Task`, it is equivalent to configuring this property for a specific `Container` of the Pod.
165+
However, the `podTemplate` of `TaskRun` can currently only override this configuration at the `Pod` level and cannot override this configuration for a specific `Container`.
166+
167+
If the user's base image must require a specific user (non-65532) to work properly, then this configuration may prevent users from using this `Task`.
168+
169+
#### Exceptions
170+
171+
For general script execution Tasks like `run-script`, **it is recommended to specify `runAsUser` in the Task** for the following reasons:
172+
173+
1. The main purpose of such Tasks is to execute general scripts, and users usually don't need to customize base images for them
174+
2. Specifying `runAsUser` allows users to:
175+
- Directly use various standard images
176+
- Avoid additional configuration in `TaskRun` or `PipelineRun`
177+
- Improve ease of use
178+
179+
> **Note**: This recommendation only applies to general script execution Tasks, other types of Tasks should still follow the above conventions.
180+
181+
### 6. Tasks Need Integration Test Coverage
182+
183+
Integration test pipelines can be placed in the `.tekton/integrations/{task-name}.yaml` directory.
184+
185+
### 7. Unified Use of `registry.alauda.cn:60070` for Image Registry Addresses Referenced in Tasks
186+
187+
Although the currently built images are usually `build-harbor.alauda.cn`, considering that this image address is inconvenient for integration testing.
188+
Therefore, it is temporarily recommended to uniformly use `registry.alauda.cn:60070` as the image registry address in Tasks.
189+
190+
### 8. Task Display Names
191+
192+
Task display names follow PascalCase convention, meaning the first letter is capitalized.
193+
194+
| Description | Bad Case | Good Case |
195+
| --------------------------------------- | ----------------- | ----------------- |
196+
| First letter capitalized | buildah | Buildah |
197+
| First letter of each word capitalized | Sonarqube scanner | Sonarqube Scanner |
198+
| Multiple words separated by spaces, not `-`, `_` | RunScript | Run Script |
199+
200+
### 9. Task HTTPS Certificates Handling
201+
202+
When adding a new Task, cover the following cases:
203+
204+
- Allow skipping certificate verification for HTTPS: expose a toggle parameter and clearly document the risks and when to use it.
205+
- Trust HTTPS via user-provided certificates: expose a workspace for mounting custom CAs/truststores.
206+
- If the tool uses a “full replacement” trust-store strategy: implement append/merge logic in the Task so user certificates are added to the default trust chain rather than overwriting it, preventing breaks to other HTTPS endpoints and improving UX.

‎docs/en/development/catalog/quick_start.mdx‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
---
2+
weight: 5
3+
status: proposed
4+
title: Catalog Development Guide
5+
creation-date: "2025-02-25"
6+
category: docs
7+
authors:
8+
- "@qingliu"
9+
---
10+
11+
# Catalog Development Guide
12+
13+
## How to Initialize a New `Task`
14+
15+
Refer to the [catalog convention](./convention.md) and the existing `maven` project to initialize a new `Task`.
16+
17+
### 1. Initialize the Main Directory `task/maven/{version}/`
18+
19+
> The directory name `task` is a convention of `TektonHub` and cannot be modified.
20+
21+
```yaml
22+
./task/maven/0.5
23+
├── README.md
24+
├── maven.yaml
25+
├── samples
26+
│ ├── pvc-pod.yaml
27+
│ └── taskrun-pvc.yaml
28+
├── features
29+
│ └── maven.feature
30+
└── testdata
31+
└── taskrun-maven-test-server-creds.yaml
32+
```
33+
34+
- `README.md` describes the functionality and usage of the `Task`
35+
- `maven.yaml` describes the specific implementation of the `Task`
36+
- `samples` directory contains usage examples for the `Task`
37+
- `features` directory contains test cases for the `Task`
38+
- `testdata` directory contains test data for the `Task`
39+
40+
### 2. Build Dependent Images
41+
42+
a. Prepare `Dockerfile` and other files for building image dependencies in `images/{taskname}/`.
43+
44+
```yaml
45+
./images/maven
46+
└── Dockerfile
47+
```
48+
49+
b. Prepare the image build pipeline file `build-maven.yaml`.
50+
51+
```yaml
52+
.tekton/images
53+
└── build-maven.yaml
54+
```
55+
56+
Pay special attention to the following areas:
57+
58+
- `pipelinesascode.tekton.dev/on-comment` trigger comment keywords
59+
- `pipelinesascode.tekton.dev/on-cel-expression` trigger conditions
60+
- `file-list-for-commit-sha` list of related files for calculating version numbers
61+
- Since this code repository contains many components, changes to other components should not affect the version number of the current component.
62+
- `update-files-based-on-image` used to perform a series of operations based on the built image
63+
- Can be used to update the `values.yaml` file in the code root directory
64+
- Can be used to automatically update the image version numbers used in the `Task`
65+
66+
:::tip
67+
Currently, only the `catalog` image build pipeline needs to configure `upstreams` for automatically updating the upstream `tektoncd-hub` repository.
68+
69+
See the [Update catalog to hub process](#update_catalog_to_hub) below for details.
70+
:::
71+
72+
c. Register new dependent images in `values.yaml`
73+
74+
> The purpose of this file is to record all images that this component depends on in the product.
75+
>
76+
> This information will be automatically synchronized to `tektoncd-hub` -> `tektoncd-operator` as needed.
77+
>
78+
> This will ultimately ensure that the `spec.relatedImages` field in the `ClusterServiceVersion` of `Tektoncd-Operator` contains this information.
79+
80+
```yaml
81+
global:
82+
registry:
83+
address: registry.alauda.cn:60070
84+
images:
85+
# Add here, subsequent tag and digest will be automatically updated
86+
maven:
87+
repository: devops/tektoncd/hub/maven
88+
digest: sha256:c5df6519e7e45607e78fc72db5dd3ff450b369b24f6ec08d7c2df81256c706c7
89+
tag: v0.1.0-beta.45.gce64259
90+
```
91+
92+
### 3. Write Integration Tests
93+
94+
- Arrange the `task/{taskname}/{version}/features/{taskname}.feature` file as needed.
95+
- Adjust the BDD code `./godods` as needed
96+
- Prepare the integration test pipeline file `.tekton/integrations/{taskname}.yaml`
97+
98+
## Workflow Process
99+
100+
- Submit PR
101+
- Automatically triggers image build pipeline, automatically updates dependent files like `values.yaml`.
102+
- Manually trigger `e2e` integration test pipeline
103+
- Merge PR
104+
- Automatically triggers `catalog` image build pipeline
105+
- Automatically triggers `tektoncd-hub` pipeline, automatically updates `values.yaml`
106+
107+
## Update Catalog to Hub Process \{#update_catalog_to_hub}
108+
109+
The `catalog` image will contain all dependent `Task`s. It will automatically trigger the build pipeline when there are changes in the `task` directory.
110+
111+
In its image build pipeline, there is a step called `upstreams` that is used to automatically update the upstream `tektoncd-hub` repository.
112+
113+
It will actively trigger the upstream `tektoncd-hub` pipeline [hub-fetch-catalog-values](https://github.com/AlaudaDevops/tektoncd-hub/blob/main/.tekton/pr-catalog-update.yaml) when there are changes in the `main` and `release` branches to automatically fetch the latest configuration file `values.yaml`.
114+
115+
The purpose of this step is to ensure that the `values.yaml` file in the `tektoncd-hub` repository also contains the latest dependent image information from `catalog`.
116+

‎docs/en/development/run_e2e.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ Before starting, please ensure your environment meets the following requirements
3131
### Step 1: Prepare Test Environment
3232

3333
```bash
34-
# Check Docker version
34+
# Check Podman version
3535
podman version
3636

3737
# Pull the E2E test image

0 commit comments

Comments
 (0)