Skip to content

Commit c1b62b5

Browse files
danielfbmdanielfbm
committed
📚 Sync docs from alaudadevops/tektoncd-operator on 810c6abe5024de122277cf4d47f1e8a3a2135a38
Source: feat: Adding system roles to be bundled with operator (#854) Author: Daniel Filipe Bruehmueller Morinigo Ref: refs/heads/main Commit: 810c6abe5024de122277cf4d47f1e8a3a2135a38 This commit automatically syncs documentation changes from the source-docs repository. 🔗 View source commit: AlaudaDevops/tektoncd-operator@810c6ab 🤖 Synced on 2025-11-26 07:43:03 UTC
1 parent 1fa465f commit c1b62b5

File tree

2 files changed

+267
-4
lines changed

2 files changed

+267
-4
lines changed

‎.github/SYNC_INFO.md‎

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

3-
- **Last synced**: 2025-11-26 05:42:51 UTC
3+
- **Last synced**: 2025-11-26 07:43:03 UTC
44
- **Source repository**: alaudadevops/tektoncd-operator
5-
- **Source commit**: [93f5dec7917efeeb48eb7165a922f210650bb696](https://github.com/alaudadevops/tektoncd-operator/commit/93f5dec7917efeeb48eb7165a922f210650bb696)
6-
- **Triggered by**: edge-katanomi-app2[bot]
7-
- **Workflow run**: [#100](https://github.com/alaudadevops/tektoncd-operator/actions/runs/19693818109)
5+
- **Source commit**: [810c6abe5024de122277cf4d47f1e8a3a2135a38](https://github.com/alaudadevops/tektoncd-operator/commit/810c6abe5024de122277cf4d47f1e8a3a2135a38)
6+
- **Triggered by**: danielfbm
7+
- **Workflow run**: [#101](https://github.com/alaudadevops/tektoncd-operator/actions/runs/19696219460)
88

99
## Files synced:
1010
- docs/

‎docs/en/development/system-roles.mdx‎

Lines changed: 263 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,263 @@
1+
# System Roles Management
2+
3+
## Overview
4+
5+
The Tekton Operator now includes a system roles feature that provides default RBAC (Role-Based Access Control) permissions for Tekton resources. These roles are automatically bundled with the operator and deployed to the cluster, ensuring that platform users have appropriate access to Tekton resources based on their role in the system.
6+
7+
## What Changed
8+
9+
### New Directory Structure
10+
11+
A new `config/system-roles/` directory has been added to the project with the following structure:
12+
13+
```
14+
config/system-roles/
15+
├── kustomization.yaml
16+
├── tekton-cluster-admin.yaml
17+
├── tekton-deployment-admin.yaml
18+
├── tekton-pipelines.yaml
19+
├── tekton-triggers-admin.yaml
20+
└── tekton-triggers.yaml
21+
```
22+
23+
### Bundle Integration
24+
25+
The system roles are now integrated into the operator bundle during the build process. The `.tekton/to-all-in-one.yaml` pipeline has been updated to include the following steps:
26+
27+
```yaml
28+
# Copy system-roles to the bundle directory
29+
cp -rf config/system-roles upstream/operatorhub/kubernetes/manifests
30+
yq e -i '.resources += "../system-roles"' upstream/operatorhub/kubernetes/manifests/fetch-strategy-release-manifest/kustomization.yaml
31+
```
32+
33+
This ensures that the system roles are packaged with each operator release and automatically applied when the operator is deployed.
34+
35+
## System Roles Explained
36+
37+
### 1. **tekton-pipelines.yaml**
38+
39+
Defines permissions for Tekton Pipeline resources including pipelines, tasks, runs, and related components.
40+
41+
**Admin Role** (`cpaas:tekton-pipelines:business-ns:admin`):
42+
- Full access (`*`) to: pipelines, pipelineruns, tasks, taskruns, stepactions, runs, customruns, pipelineresources
43+
- Full access to Tekton Hub resources
44+
- Full access to Pipelines as Code repositories
45+
- Full access to scheduled triggers
46+
- Full access to resolution requests and results
47+
48+
**View Role** (`cpaas:tekton-pipelines:business-ns:view`):
49+
- Read-only access (get, list, watch) to all the above resources
50+
51+
**Aggregates to**: cluster-admin, namespace-admin, namespace-developer, platform-admin, project-admin, platform-auditor
52+
53+
### 2. **tekton-triggers.yaml**
54+
55+
Defines permissions for Tekton Triggers resources (triggers, triggertemplates, triggerbindings).
56+
57+
**Admin Role** (`cpaas:tekton-triggers:business-ns:admin`):
58+
- Full access to triggers, triggertemplates, and triggerbindings
59+
60+
**View Role** (`cpaas:tekton-triggers:business-ns:view`):
61+
- Read-only access to triggers, triggertemplates, and triggerbindings
62+
63+
**Aggregates to**: Similar to tekton-pipelines roles
64+
65+
### 3. **tekton-triggers-admin.yaml**
66+
67+
Defines elevated permissions for managing EventListeners and Interceptors.
68+
69+
**Admin Role** (`cpaas:tekton-triggers-admin:business-ns:admin`):
70+
- Full access to interceptors, eventlisteners, and eventlisteners/finalizers
71+
72+
**View Role** (`cpaas:tekton-triggers-admin:business-ns:view`):
73+
- Read-only access to interceptors, eventlisteners, and eventlisteners/finalizers
74+
75+
**Aggregates to**: cluster-admin, namespace-admin, platform-admin, project-admin
76+
77+
### 4. **tekton-cluster-admin.yaml**
78+
79+
Defines permissions for cluster-scoped Tekton resources.
80+
81+
**Admin Role** (`cpaas:tekton-cluster-admin:business-ns:admin`):
82+
- Full access to clustertasks, clustertriggerbindings, and clusterinterceptors
83+
84+
**View Role** (`cpaas:tekton-cluster-admin:business-ns:view`):
85+
- Read-only access to clustertasks, clustertriggerbindings, and clusterinterceptors
86+
87+
**Aggregates to**: cluster-admin, platform-admin
88+
89+
### 5. **tekton-deployment-admin.yaml**
90+
91+
Defines permissions for managing Tekton operator CRDs (TektonPipeline, TektonTrigger, etc.).
92+
93+
**Admin Role** (`cpaas:tekton-deployment-admin:business-ns:admin`):
94+
- Full access to all `operator.tekton.dev` resources
95+
96+
**View Role** (`cpaas:tekton-deployment-admin:business-ns:view`):
97+
- Read-only access to all `operator.tekton.dev` resources
98+
99+
**Aggregates to**: cluster-admin, platform-admin, platform-auditor
100+
101+
## How to Modify System Roles
102+
103+
### When to Modify
104+
105+
Developers should modify system roles when:
106+
107+
1. **Adding New Tekton Resources**: When new CRDs or API groups are introduced
108+
2. **Changing Permission Requirements**: When security policies require different access levels
109+
3. **Fixing Permission Issues**: When users report access denied errors for legitimate operations
110+
4. **Deprecating Resources**: When removing support for certain resources
111+
112+
### Steps to Modify
113+
114+
1. **Identify the Correct File**: Determine which role file needs to be updated based on the resource type:
115+
- Pipeline resources → `tekton-pipelines.yaml`
116+
- Trigger resources → `tekton-triggers.yaml` or `tekton-triggers-admin.yaml`
117+
- Cluster-scoped resources → `tekton-cluster-admin.yaml`
118+
- Operator CRDs → `tekton-deployment-admin.yaml`
119+
120+
2. **Edit the Role Definition**: Update the ClusterRole rules with the new permissions:
121+
122+
```yaml
123+
apiVersion: rbac.authorization.k8s.io/v1
124+
kind: ClusterRole
125+
metadata:
126+
labels:
127+
rbac.cpaas.io/aggregate-to-cluster-admin: "true"
128+
# ... other aggregation labels
129+
name: cpaas:tekton-new-resource:business-ns:admin
130+
rules:
131+
- apiGroups:
132+
- your.api.group
133+
resources:
134+
- yourresource
135+
- yourresource/status
136+
verbs:
137+
- '*' # or specific verbs: get, list, watch, create, update, delete
138+
```
139+
140+
3. **Update kustomization.yaml**: If adding a new role file, add it to `config/system-roles/kustomization.yaml`:
141+
142+
```yaml
143+
resources:
144+
- tekton-cluster-admin.yaml
145+
- tekton-deployment-admin.yaml
146+
- tekton-pipelines.yaml
147+
- tekton-triggers-admin.yaml
148+
- tekton-triggers.yaml
149+
- your-new-role.yaml # Add new file here
150+
```
151+
152+
4. **Test Locally**: Build and test the changes locally:
153+
154+
```bash
155+
# Generate the bundle
156+
make bundle
157+
158+
# Verify the roles are included
159+
cat upstream/operatorhub/kubernetes/release-artifacts/bundle/manifests/*.yaml | grep -A 20 "kind: ClusterRole"
160+
```
161+
162+
5. **Commit and Create PR**: Submit your changes following the standard Git workflow.
163+
164+
### Best Practices
165+
166+
1. **Use Aggregation Labels**: Always include appropriate `rbac.cpaas.io/aggregate-to-*` labels to ensure roles are properly inherited by higher-level roles.
167+
168+
2. **Follow Naming Convention**: Use the pattern `cpaas:<component>:<scope>:<permission>` for role names.
169+
170+
3. **Separate Admin and View Roles**: Always create both admin (full access) and view (read-only) versions of each role.
171+
172+
4. **Document Changes**: Update this documentation when adding or modifying roles.
173+
174+
5. **Consider Least Privilege**: Only grant the minimum permissions necessary for each role.
175+
176+
6. **Test with Multiple Personas**: Verify that:
177+
- Cluster admins have full access
178+
- Namespace admins have appropriate namespace-scoped access
179+
- Developers have necessary permissions without excessive privileges
180+
- Auditors have read-only access
181+
182+
### Example: Adding a New Resource Type
183+
184+
Suppose you need to add permissions for a new custom resource `buildpacks.tekton.dev`:
185+
186+
```yaml
187+
# Add to tekton-pipelines.yaml
188+
---
189+
apiVersion: rbac.authorization.k8s.io/v1
190+
kind: ClusterRole
191+
metadata:
192+
labels:
193+
rbac.cpaas.io/aggregate-to-cluster-admin: "true"
194+
rbac.cpaas.io/aggregate-to-namespace-admin: "true"
195+
rbac.cpaas.io/aggregate-to-namespace-developer: "true"
196+
rbac.cpaas.io/aggregate-to-platform-admin: "true"
197+
rbac.cpaas.io/aggregate-to-project-admin: "true"
198+
rbac.cpaas.io/aggregate-to-scope-business-ns: "true"
199+
name: cpaas:tekton-buildpacks:business-ns:admin
200+
rules:
201+
- apiGroups:
202+
- tekton.dev
203+
resources:
204+
- buildpacks
205+
- buildpacks/status
206+
verbs:
207+
- '*'
208+
---
209+
apiVersion: rbac.authorization.k8s.io/v1
210+
kind: ClusterRole
211+
metadata:
212+
labels:
213+
rbac.cpaas.io/aggregate-to-platform-auditor: "true"
214+
rbac.cpaas.io/aggregate-to-scope-business-ns: "true"
215+
name: cpaas:tekton-buildpacks:business-ns:view
216+
rules:
217+
- apiGroups:
218+
- tekton.dev
219+
resources:
220+
- buildpacks
221+
- buildpacks/status
222+
verbs:
223+
- get
224+
- list
225+
- watch
226+
```
227+
228+
## Troubleshooting
229+
230+
### Roles Not Applied
231+
232+
If system roles are not being applied after deployment:
233+
234+
1. Check that the bundle build completed successfully
235+
2. Verify the roles are present in the bundle manifests:
236+
```bash
237+
kubectl get clusterroles | grep cpaas:tekton
238+
```
239+
3. Check operator logs for any errors during role creation
240+
241+
### Permission Denied Errors
242+
243+
If users report permission denied errors:
244+
245+
1. Identify which resource and operation is being denied
246+
2. Check which role should grant that permission
247+
3. Verify the user has the appropriate role binding
248+
4. Update the system role if the permission should be included
249+
250+
### Role Aggregation Not Working
251+
252+
If roles are not being aggregated correctly:
253+
254+
1. Verify the aggregation labels match the parent role's `aggregationRule`
255+
2. Check that ClusterRoleBindings exist for the parent roles
256+
3. Ensure the operator has permissions to create ClusterRoles and ClusterRoleBindings
257+
258+
## Related Resources
259+
260+
- [Kubernetes RBAC Documentation](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)
261+
- [Role Aggregation](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#aggregated-clusterroles)
262+
- [Tekton RBAC](https://tekton.dev/docs/pipelines/auth/)
263+
- [Permission migration guide](https://gitlab-ce.alauda.cn/devops/tech-research/permission-migrator/-/blob/main/docs/MIGRATE.md#%E6%96%B0%E6%97%A7%E8%BD%AC%E6%8D%A2%E8%A7%84%E5%88%99)

0 commit comments

Comments
 (0)