Skip to content

Commit 7e0ad05

Browse files
author
edge-katanomi-app2[bot]
committed
📚 Sync docs from alaudadevops/tektoncd-operator on 17a18250a6ccf81f70fcf0c79e9ec336c665e49b
Source: chore: trigger template relate trigger doc (#594) Author: still fantasy Ref: refs/heads/main Commit: 17a18250a6ccf81f70fcf0c79e9ec336c665e49b This commit automatically syncs documentation changes from the source-docs repository. 🔗 View source commit: https://github.com/alaudadevops/tektoncd-operator/commit/17a18250a6ccf81f70fcf0c79e9ec336c665e49b 🤖 Synced on 2025-09-22 08:30:57 UTC
1 parent 752a83c commit 7e0ad05

File tree

2 files changed

+275
-3
lines changed

2 files changed

+275
-3
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-09-19 03:07:46 UTC
3+
- **Last synced**: 2025-09-22 08:30:57 UTC
44
- **Source repository**: alaudadevops/tektoncd-operator
5-
- **Source commit**: [80bf37a5daf148f1e94bad74f207dc96d28cbdcf](https://github.com/alaudadevops/tektoncd-operator/commit/80bf37a5daf148f1e94bad74f207dc96d28cbdcf)
5+
- **Source commit**: [17a18250a6ccf81f70fcf0c79e9ec336c665e49b](https://github.com/alaudadevops/tektoncd-operator/commit/17a18250a6ccf81f70fcf0c79e9ec336c665e49b)
66
- **Triggered by**: edge-katanomi-app2[bot]
7-
- **Workflow run**: [#71](https://github.com/alaudadevops/tektoncd-operator/actions/runs/17847294232)
7+
- **Workflow run**: [#72](https://github.com/alaudadevops/tektoncd-operator/actions/runs/17909405105)
88

99
## Files synced:
1010
- docs/

‎docs/en/teps/0002_relate_triggertemplate_to_trigger.md‎

Lines changed: 272 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,272 @@
1+
---
2+
title: Relate TriggerTemplate to Trigger
3+
authors:
4+
- [email protected]
5+
creation-date: 2025-09-18
6+
last-updated: 2025-09-18
7+
status: proposed
8+
---
9+
10+
# TEP-0001: Relate TriggerTemplate to Trigger
11+
12+
## Record of changes
13+
14+
| Order | Change of content | Reason for change | Change of time | Change of executor | Approved by |
15+
| :---- | :---------------- | :---------------- | -------------- | :----------------- | :---------- |
16+
17+
## Summary
18+
19+
This proposal aims to relate existing `TriggerTemplate` resources to `Trigger` resources.
20+
21+
In the process of creating a `Trigger`, you can easily refer to an existing `TriggerTemplate` to complete the creation work.
22+
23+
## Motivation
24+
25+
Currently, when creating `Trigger`, users often need to repeatedly configure similar template such as `params`, `workspaces`, `serviceAccountName`, `podTemplate` etc.
26+
This repetitive configuration is inefficient and cumbersome, and is not conducive to unified maintenance.
27+
28+
### Goals
29+
30+
- Supports direct use of an existing `TriggerTemplate` when creating `Trigger`
31+
- The parameters passed through the `TriggerBinding` of the `Trigger` event can be used in the `TriggerTemplate`
32+
- Maintain compatibility with existing Tekton Triggers APIs
33+
34+
### Non-Goals
35+
36+
- Modifying the core `TriggerTemplate` API structure
37+
- Provides a new resource type for `Trigger` creation to use
38+
- Automating the selection of configuration templates
39+
40+
### Use Cases
41+
42+
1. **Trigger Refer to TriggerTemplate**
43+
44+
- Supports direct use of an existing `TriggerTemplate` when creating `Trigger`
45+
46+
2. **TriggerTemplate uses the TriggerBinding parameters**
47+
48+
- The parameters of the `TriggerBinding` can be used in the `TriggerTemplate`
49+
50+
### Requirements
51+
52+
- Must utilize existing `TriggerTemplate` resources without API modifications
53+
- Must maintain backward compatibility with existing trigger-based usage
54+
- Must support template merge rules for combining multiple configuration templates
55+
56+
## Design Details
57+
58+
### Core ideas
59+
60+
The core of this solution is to introduce new metadata (Labels) for `TriggerTemplate` to be able to declare their required parameter sources (i.e. `TriggerBinding`). Compatible `TriggerTemplate` can then be auto-discovered based on the selected `TriggerBinding` when the `Trigger` is created.
61+
62+
#### Declaration
63+
64+
When creating a `TriggerTemplate`, the user specifies `TriggerBinding` that are compatible with its design.The system records this relationship in the Label of the `TriggerTemplate`.
65+
66+
#### Discovery
67+
68+
When creating a `Trigger`, when the user selects a `TriggerBinding`, the system can query the Label Selector to find all the `TriggerTemplate` declared to be compatible with this `TriggerBinding` for the user to select.
69+
70+
### Label Design
71+
72+
We will use a specific Label on the `TriggerTemplate` to identify its association with the `TriggerBinding`.
73+
74+
| Key | Value |
75+
| :------------------------------------------- | :------------ |
76+
| triggertemplate.triggers.tekton.dev/bindings | <bindingName> |
77+
78+
**Instructions**:
79+
80+
- <bindingName> is the name of the resource for `TriggerBinding`
81+
82+
**Example**:
83+
84+
```yaml
85+
labels:
86+
triggers.tekton.dev/bindings: "github-push-binding"
87+
```
88+
89+
### Parameter Mapping and verification
90+
91+
`Triggertemplate` spec.params field defines the list of parameters it needs. `Triggerbinding` spec.params field defines the list of parameters it can provide.
92+
**Compatibility rules**:
93+
`TriggerBinding`B can be used to instantiate `TriggerTemplate`T if and only if the set of parameters that B can provide contains the set of parameters required by T (disregarding parameters with default values).
94+
95+
### Trigger template discovery mechanism
96+
97+
In a user interface or automated process, the steps to create a `Trigger` are as follows:
98+
99+
1. The user selects a name for `Triggerbinding` (e.g. gitlab-push).
100+
2. The system uses Label Selector triggertemplate.triggers.tekton.dev/bindings=gitlab-push query all of `TriggerTemplate`.
101+
3. The system displays a list of filtered `TriggerTemplate` to the user.
102+
4. The user selects a `TriggerTemplate` reference from the list to configure the `Trigger`.
103+
104+
### Example of a resource definition
105+
106+
#### TriggerBinding
107+
108+
```yaml
109+
apiVersion: triggers.tekton.dev/v1beta1
110+
kind: ClusterTriggerBinding
111+
metadata:
112+
labels:
113+
cpaas.io/tool: gitlab
114+
operator.tekton.dev/operand-name: tektoncd-triggers
115+
name: gitlab-push
116+
spec:
117+
params:
118+
- name: project-id
119+
value: $(body.project.id)
120+
- name: project-name
121+
value: $(body.project.name)
122+
- name: project-path
123+
value: $(body.project.path_with_namespace)
124+
- name: project-web-url
125+
value: $(body.project.web_url)
126+
- name: git-repo-url
127+
value: $(body.project.git_http_url)
128+
- name: git-repo-ssh-url
129+
value: $(body.project.git_ssh_url)
130+
- name: git-repo-name
131+
value: $(body.repository.name)
132+
- name: user-name
133+
value: $(body.user_name)
134+
- name: user-username
135+
value: $(body.user_username)
136+
- name: user-email
137+
value: $(body.user_email)
138+
- name: git-revision
139+
value: $(body.ref)
140+
- name: git-commit-sha
141+
value: $(body.checkout_sha)
142+
- name: git-commit-message
143+
value: $(body.commits[0].message)
144+
- name: git-commit-timestamp
145+
value: $(body.commits[0].timestamp)
146+
```
147+
148+
#### TriggerTemplate
149+
150+
```yaml
151+
apiVersion: triggers.tekton.dev/v1beta1
152+
kind: TriggerTemplate
153+
metadata:
154+
name: my-template
155+
labels:
156+
triggertemplate.triggers.tekton.dev/bindings: "gitlab-push"
157+
spec:
158+
params:
159+
- name: project-id
160+
- name: project-name
161+
- name: project-path
162+
- name: project-web-url
163+
- name: git-repo-url
164+
- name: git-repo-ssh-url
165+
- name: git-repo-name
166+
- name: user-name
167+
- name: user-username
168+
- name: user-email
169+
- name: git-revision
170+
- name: git-commit-sha
171+
- name: git-commit-message
172+
- name: git-commit-timestamp
173+
174+
resourcetemplates:
175+
- apiVersion: tekton.dev/v1beta1
176+
kind: PipelineRun
177+
metadata:
178+
generateName: my-app-build-
179+
spec:
180+
pipelineRef:
181+
name: build-and-push-pipeline
182+
params:
183+
- name: revision
184+
value: $(tt.params.git-revision)
185+
- name: url
186+
value: $(tt.params.git-repo-url)
187+
workspaces:
188+
- name: source
189+
emptyDir: {}
190+
```
191+
192+
#### Trigger
193+
194+
### Compatibility
195+
196+
When the `TriggerTemplate` bound to `TriggerBinding` is used as a pipelined execution template, the variable write is replaced with a concrete default value.
197+
198+
```yaml
199+
apiVersion: triggers.tekton.dev/v1beta1
200+
kind: Trigger
201+
metadata:
202+
name: my-github-trigger
203+
spec:
204+
bindings:
205+
- ref: gitlab-push
206+
kind: ClusterTriggerBinding
207+
template:
208+
ref: my-app-build-template # Use the template associated with the above binding
209+
interceptors:
210+
- ref:
211+
name: "github"
212+
params:
213+
- name: "secretRef"
214+
value:
215+
secretName: github-secret
216+
secretKey: secretToken
217+
- name: "eventTypes"
218+
value: ["push"]
219+
```
220+
221+
## Design Evaluation
222+
223+
### Reusability
224+
225+
- `TriggerTemplate` can be reused across multiple `Trigger`
226+
- Parameterization allows for customization while maintaining consistency
227+
228+
### Simplicity
229+
230+
- Uses existing `TriggerTemplate` resources without API changes, leveraging familiar structure
231+
- Clear labeling conventions (`triggertemplate.triggers.tekton.dev/bindings`) for easy identification
232+
- Standardized annotation conventions (`tekton.dev/displayName`, `tekton.dev/description`) for metadata
233+
- Single resource template limitation simplifies configuration and reduces complexity
234+
235+
### Consistency
236+
237+
- Standardized configuration patterns across task and pipeline executions
238+
- Reduces configuration errors through templating and validation
239+
- Ensures consistent security settings, resource allocations, and execution environments
240+
- Clear template selection rules prevent ambiguity in configuration resolution
241+
242+
### User Experience
243+
244+
- Eliminates repetitive runtime configuration work for Trigger
245+
- Trigger can be managed based on triggerTemplate
246+
- Clear labeling and annotation conventions improve discoverability and documentation
247+
- Maintains backward compatibility with existing TriggerTemplate usage
248+
- Human-readable display names and descriptions enhance template management
249+
250+
### Performance
251+
252+
- No additional API overhead since existing TriggerTemplate resources are reused
253+
- Efficient template resolution through Kubernetes label-based filtering
254+
- Minimal impact on existing trigger functionality due to clear separation of concerns
255+
- Single resource template limitation reduces processing complexity
256+
- Template merge rules are based on proven Kubernetes merge patterns
257+
258+
### Security
259+
260+
- The functions provided fulfill https encrypted access.
261+
- Triggers do not have the right to read user information directly
262+
- All the operations of the trigger resources to meet the audit requirements
263+
264+
## References
265+
266+
- [Tekton Triggers Documentation](https://tekton.dev/docs/triggers/)
267+
- [Tekton Pipeline Documentation](https://tekton.dev/docs/pipelines/)
268+
- [Kubernetes Labeling Best Practices](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)
269+
- API References
270+
- [TriggerTemplate API Reference](../apis/kubernetes_apis/triggers/triggertemplate.mdx)
271+
- [TriggerBinding API Reference](../apis/kubernetes_apis/triggers/triggerbinding.mdx)
272+
- [Trigger API Reference](../apis/kubernetes_apis/triggers/triggers.mdx)

0 commit comments

Comments
 (0)