chore: Describe RBAC rules, remove unnecessary rules (#767)

* chore: Describe RBAC rules, remove unnecessary rules

* chore: Update changelog

* chore: Simplify RBAC descriptions

They were a bit too verbose

* fix: CRD permissions

- Add missing description
- Remove `get`, it is never used
- Make list/watch unconditional

* chore: Reword

* chore: Keep rbac.authorization.k8s.io rules together

* chore: Remove permissions for AirflowCluster role

This was never needed, and if an end-user does happen to need their code reading secrets/configmaps, they should create the applicable role and binding.

* chore: Remove unused code

* chore(nix): Update hashes to avoid mismatch

* chore: Split operator and product roles into separate files

* Apply suggestions from code review

Co-authored-by: Techassi <git@techassi.dev>

* chore: Remove unused node list/watch permissions

* Apply suggestions from code review

Co-authored-by: Techassi <git@techassi.dev>

---------

Co-authored-by: Techassi <git@techassi.dev>

Author: NickLarsenNZ

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+### Changed
+
+- Document Helm deployed RBAC permissions and remove unnecessary permissions ([#767]).
+
+- [#767]: https://github.com/stackabletech/airflow-operator/pull/767
+
 ## [26.3.0] - 2026-03-16
 
 ## [26.3.0-rc1] - 2026-03-16

Cargo.nix

@@ -6,37 +6,32 @@ metadata:
   labels:
   {{- include "operator.labels" . | nindent 4 }}
 rules:
-  - apiGroups:
-      - ""
-    resources:
-      - nodes
-    verbs:
-      - list
-      - watch
   # For automatic cluster domain detection
   - apiGroups:
       - ""
     resources:
       - nodes/proxy
     verbs:
       - get
+  # Manage core workload resources created per AirflowCluster.
+  # All resources are applied via Server-Side Apply (create + patch) and tracked for
+  # orphan cleanup (list + delete).
   - apiGroups:
       - ""
     resources:
-      - pods
       - configmaps
       - secrets
       - services
-      - endpoints
       - serviceaccounts
     verbs:
       - create
       - delete
       - get
       - list
       - patch
-      - update
       - watch
+  # Per AirflowCluster RoleBinding for the workload ServiceAccount to the airflow-clusterrole.
+  # Applied via SSA (create + patch), tracked for orphan cleanup (list + delete).
   - apiGroups:
       - rbac.authorization.k8s.io
     resources:
@@ -47,32 +42,31 @@ rules:
       - get
       - list
       - patch
-      - update
-      - watch
+  # Allows the operator to create RoleBindings that reference the airflow-clusterrole
+  # (the product ClusterRole bound to workload pods, defined below)
   - apiGroups:
-      - apps
+      - rbac.authorization.k8s.io
     resources:
-      - statefulsets
+      - clusterroles
     verbs:
-      - get
-      - create
-      - delete
-      - list
-      - patch
-      - update
-      - watch
+      - bind
+    resourceNames:
+      - {{ include "operator.name" . }}-clusterrole
+  # StatefulSets for each role group (webserver, scheduler, worker, triggerer, dag-processor).
+  # Applied via SSA (create + patch), tracked for orphan cleanup (list + delete).
   - apiGroups:
-      - batch
+      - apps
     resources:
-      - jobs
+      - statefulsets
     verbs:
       - create
       - delete
       - get
       - list
       - patch
-      - update
       - watch
+  # PodDisruptionBudgets per role to protect against simultaneous pod evictions.
+  # Applied via SSA (create + patch), tracked for orphan cleanup (list + delete).
   - apiGroups:
       - policy
     resources:
@@ -83,49 +77,54 @@ rules:
       - get
       - list
       - patch
-      - update
-      - watch
+  # Required for maintaining the CRDs within the operator (including the conversion webhook info).
+  # Also for the startup condition check before the controller can run.
   - apiGroups:
       - apiextensions.k8s.io
     resources:
       - customresourcedefinitions
     verbs:
-      - get
       # Required to maintain the CRD. The operator needs to do this, as it needs to enter e.g. it's
       # generated certificate in the conversion webhook.
       {{- if .Values.maintenance.customResourceDefinitions.maintain }}
       - create
       - patch
+      {{- end }}
       # Required for startup condition
       - list
       - watch
-      {{- end }}
+  # Listener for the Webserver role to expose HTTP access via a configurable ListenerClass.
+  # Applied via SSA (create + patch), tracked for orphan cleanup (list + delete).
   - apiGroups:
       - listeners.stackable.tech
     resources:
       - listeners
     verbs:
+      - create
+      - delete
       - get
       - list
-      - watch
       - patch
-      - create
-      - delete
+  # Primary reconciliation target: the controller watches AirflowCluster resources (list + watch)
+  # and reads them during reconciliation (get).
   - apiGroups:
       - {{ include "operator.name" . }}.stackable.tech
     resources:
       - {{ include "operator.name" . }}clusters
     verbs:
       - get
       - list
-      - patch
       - watch
+  # Write reconciliation status conditions back to AirflowCluster objects
   - apiGroups:
       - {{ include "operator.name" . }}.stackable.tech
     resources:
       - {{ include "operator.name" . }}clusters/status
     verbs:
       - patch
+  # Resolve TLS and authentication provider configuration.
+  # Watched (list + watch) to re-reconcile when an AuthenticationClass changes,
+  # and fetched individually (get) during reconciliation via resolve_class().
   - apiGroups:
       - authentication.stackable.tech
     resources:
@@ -134,69 +133,11 @@ rules:
       - get
       - list
       - watch
+  # Publish Kubernetes events for reconciliation activity
   - apiGroups:
       - events.k8s.io
     resources:
       - events
     verbs:
       - create
       - patch
-  - apiGroups:
-      - rbac.authorization.k8s.io
-    resources:
-      - clusterroles
-    verbs:
-      - bind
-    resourceNames:
-      - {{ include "operator.name" . }}-clusterrole
----
-apiVersion: rbac.authorization.k8s.io/v1
-kind: ClusterRole
-metadata:
-  name: {{ include "operator.name" . }}-clusterrole
-  labels:
-  {{- include "operator.labels" . | nindent 4 }}
-rules:
-  - apiGroups:
-      - ""
-    resources:
-      - configmaps
-      - secrets
-      - serviceaccounts
-    verbs:
-      - get
-  - apiGroups:
-      - ""
-    resources:
-      - pods
-    verbs:
-      - create
-      - delete
-      - get
-      - list
-      - patch
-      - update
-      - watch
-  - apiGroups:
-      - ""
-    resources:
-      - pods/log
-    verbs:
-      - get
-  - apiGroups:
-      - events.k8s.io
-    resources:
-      - events
-    verbs:
-      - create
-      - patch
-{{ if .Capabilities.APIVersions.Has "security.openshift.io/v1" }}
-  - apiGroups:
-      - security.openshift.io
-    resources:
-      - securitycontextconstraints
-    resourceNames:
-      - nonroot-v2
-    verbs:
-      - use
-{{ end }}

crate-hashes.json

@@ -0,0 +1,49 @@
+---
+# Product ClusterRole: bound (via per AirflowCluster RoleBinding) to the ServiceAccount that Airflow
+# workload pods (webserver, scheduler, worker, triggerer, dag-processor) run as.
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: {{ include "operator.name" . }}-clusterrole
+  labels:
+  {{- include "operator.labels" . | nindent 4 }}
+rules:
+  # KubernetesExecutor: the Airflow scheduler creates, monitors, and cleans up task pods directly
+  - apiGroups:
+      - ""
+    resources:
+      - pods
+    verbs:
+      - create
+      - delete
+      - get
+      - list
+      - patch
+      - update
+      - watch
+  # KubernetesExecutor: the scheduler reads task pod logs for display in the Airflow UI
+  - apiGroups:
+      - ""
+    resources:
+      - pods/log
+    verbs:
+      - get
+  # Airflow components publish Kubernetes events
+  - apiGroups:
+      - events.k8s.io
+    resources:
+      - events
+    verbs:
+      - create
+      - patch
+{{ if .Capabilities.APIVersions.Has "security.openshift.io/v1" }}
+  # On OpenShift: allows workload pods to use the nonroot-v2 SecurityContextConstraint
+  - apiGroups:
+      - security.openshift.io
+    resources:
+      - securitycontextconstraints
+    resourceNames:
+      - nonroot-v2
+    verbs:
+      - use
+{{ end }}