OCPBUGS#52452: Grant ce permissions

_topic_maps/_topic_map.yml

@@ -2224,6 +2224,8 @@ Topics:
   Topics:
   - Name: Supported extensions
     File: olmv1-supported-extensions
+  - Name: Granting permissions for cluster extensions
+    File: granting-ce-permissions
   - Name: Managing extensions
     File: managing-ce
   - Name: Extension configuration

extensions/ce/granting-ce-permissions.adoc

@@ -0,0 +1,36 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="granting-ce-permissions"]
+= Granting permissions for cluster extensions
+include::_attributes/common-attributes.adoc[]
+:context: granting-ce-permissions
+
+toc::[]
+
+[role="_abstract"]
+Grant cluster extensions permissions to install, update, and remove cluster resources. Proper permissions ensure Operators work correctly and clean up resources when uninstalled.
+
+include::snippets/olmv1-cli-only.adoc[]
+
+include::modules/olmv1-cluster-extension-permissions.adoc[leveloffset=+1]
+
+include::modules/olmv1-creating-a-namespace.adoc[leveloffset=+1]
+
+include::modules/olmv1-creating-a-service-account.adoc[leveloffset=+1]
+
+include::modules/olmv1-creating-a-cluster-role.adoc[leveloffset=+1]
+
+include::modules/olmv1-creating-a-cluster-role-binding.adoc[leveloffset=+1]
+
+include::modules/olmv1-manual-cluster-role-scoping.adoc[leveloffset=+1]
+
+include::modules/olmv1-downloading-bundle-manifests.adoc[leveloffset=+2]
+
+include::modules/olmv1-required-rbac-to-install-and-manage-extension-resources.adoc[leveloffset=+2]
+
+include::modules/olmv1-example-pipelines-operator-cluster-role.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+[id="additional-resources_{context}"]
+== Additional resources
+
+* xref:../../authentication/using-rbac.adoc#rbac-projects-namespaces_using-rbac[Projects and namespaces]

extensions/ce/managing-ce.adoc

@@ -15,22 +15,6 @@ include::modules/olmv1-finding-operators-to-install.adoc[leveloffset=+1]
 
 include::modules/olmv1-catalog-queries.adoc[leveloffset=+2]
 
-include::modules/olmv1-cluster-extension-permissions.adoc[leveloffset=+1]
-
-include::modules/olmv1-creating-a-namespace.adoc[leveloffset=+2]
-
-include::modules/olmv1-creating-a-service-account.adoc[leveloffset=+2]
-
-include::modules/olmv1-downloading-bundle-manifests.adoc[leveloffset=+2]
-
-include::modules/olmv1-required-rbac-to-install-and-manage-extension-resources.adoc[leveloffset=+2]
-
-include::modules/olmv1-creating-a-cluster-role.adoc[leveloffset=+2]
-
-include::modules/olmv1-example-pipelines-operator-cluster-role.adoc[leveloffset=+2]
-
-include::modules/olmv1-creating-a-cluster-role-binding.adoc[leveloffset=+2]
-
 include::modules/olmv1-installing-an-operator.adoc[leveloffset=+1]
 
 include::modules/olmv1-installing-an-operator-in-a-specific-namespace.adoc[leveloffset=+1]
@@ -42,7 +26,7 @@ include::modules/olmv1-installing-an-operator-in-a-specific-namespace.adoc[level
 
 * xref:../../authentication/using-rbac.adoc#rbac-projects-namespaces_using-rbac[Projects and namespaces]
 
-* xref:../../extensions/ce/managing-ce.adoc#olmv1-creating-a-service-account_managing-ce[Creating a service account]
+* xref:../../extensions/ce/granting-ce-permissions.adoc#granting-ce-permissions[Granting permissions for cluster extensions]
 
 * xref:../../extensions/ce/update-paths.adoc#olmv1-about-target-versions_update-paths[Example custom resources (CRs) that specify a target version]
 

extensions/ce/user-access-resources.adoc

@@ -17,7 +17,7 @@ The RBAC permissions described for user access to extension resources are differ
 
 [role="_additional-resources"]
 .Additional resources
-* xref:../../extensions/ce/managing-ce.adoc#olmv1-cluster-extension-permissions_managing-ce["Managing extensions" -> "Cluster extension permissions"]
+* xref:../../extensions/ce/granting-ce-permissions.adoc#olmv1-cluster-extension-permissions_granting-ce-permissions[Cluster extension permissions]
 
 include::modules/olmv1-default-cluster-roles-users.adoc[leveloffset=+1]
 

modules/olmv1-cluster-extension-permissions.adoc

@@ -1,20 +1,31 @@
 // Module included in the following assemblies:
 //
-// * extensions/ce/managing-ce.adoc
+// * extensions/ce/granting-ce-permissions.adoc
 
 :_mod-docs-content-type: CONCEPT
 
 [id="olmv1-cluster-extension-permissions_{context}"]
 = Cluster extension permissions
 
-In {olmv0-first}, a single service account with cluster administrator privileges manages all cluster extensions.
+In {olmv0-first}, a single service account with cluster administrator privileges manages all Operators.
 
-{olmv1} is designed to be more secure than {olmv0} by default. {olmv1} manages a cluster extension by using the service account specified in an extension's custom resource (CR). Cluster administrators can create a service account for each cluster extension. As a result, administrators can follow the principle of least privilege and assign only the role-based access controls (RBAC) to install and manage that extension.
+{olmv1} manages cluster extensions by using the service account specified in the custom resource (CR) that defines the extension. Cluster administrators can create a service account for each cluster extension and assign the minimum role-based access controls (RBAC) required to install and manage that extension.
+
+[id="olmv1-rbac-structure_{context}"]
+== RBAC structure
 
 You must add each permission to either a cluster role or role. Then you must bind the cluster role or role to the service account with a cluster role binding or role binding.
 
 You can scope the RBAC to either the cluster or to a namespace. Use cluster roles and cluster role bindings to scope permissions to the cluster. Use roles and role bindings to scope permissions to a namespace. Whether you scope the permissions to the cluster or to a namespace depends on the design of the extension you want to install and manage.
 
-include::snippets/olmv1-manual-rbac-scoping-admonition.adoc[]
+[id="olmv1-permissions-approaches_{context}"]
+== Permissions approaches
+
+You can grant permissions by using one of the following approaches:
+
+// FIXUP: Reword this explanation and conform to mod docs
+Use a cluster role template:: Create a template cluster role for similar Operators. This approach works for most Red Hat catalog Operators and simplifies the setup process. For an example, see "Example cluster role for the {pipelines-title} Operator".
+
+Manually scope RBAC:: Inspect extension bundles to create least-privilege RBAC tailored to specific Operators. This approach provides fine-grained security controls but requires maintaining permissions as Operator requirements change. For more information, see "Manual cluster role scoping".
 
 If a new version of an installed extension requires additional permissions, {olmv1} halts the update process until a cluster administrator grants those permissions.

modules/olmv1-creating-a-cluster-role-binding.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * extensions/ce/managing-ce.adoc
+// * extensions/ce/granting-ce-permissions.adoc
 
 :_mod-docs-content-type: PROCEDURE
 

modules/olmv1-creating-a-cluster-role.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * extensions/ce/managing-ce.adoc
+// * extensions/ce/granting-ce-permissions.adoc
 
 :_mod-docs-content-type: PROCEDURE
 
@@ -70,7 +70,7 @@ rules:
 ----
 <1> Specifies the value from the `metadata.name` field from the custom resource (CR) of the extension.
 
-. Search for the `clusterrole` and `clusterrolebindings` values in the `rules.resources` field in the extension's CSV file.
+. Search for the `clusterrole` and `clusterrolebindings` values in the `spec.install.spec.clusterPermissions` field in the extension's CSV file.
 
 ** Copy the API groups, resources, verbs, and resource names to your manifest, similar to the following example:
 +
@@ -127,7 +127,7 @@ rules:
 <1> You cannot scope `create`, `list`, and `watch` permissions to specific resource names (the `resourceNames` field). You must scope these permissions to their resources (the `resources` field).
 <2> Some resource names are generated by using the following format: `<package_name>.<hash>`. After you install the extension, look up the resource names for the cluster roles and cluster role bindings for the controller of the extension. Replace the wildcard characters in this example with the generated names and follow the principle of least privilege.
 
-. Search for the `customresourcedefinitions` value in the `rules.resources` field in the extension's CSV file.
+. Search for the `customresourcedefinitions` value in the `spec.customresourcedefinitions.owned` field in the extension's CSV file.
 
 ** Copy the API groups, resources, verbs, and resource names to your manifest, similar to the following example:
 +
@@ -171,7 +171,7 @@ rules:
 # ...
 ----
 
-. Search the CSV file for stanzas with the `permissions` and `clusterPermissions` values in the `rules.resources` spec.
+. Search the CSV file for the `spec.install.spec.clusterPermissions` and `spec.install.spec.permissions` fields.
 
 ** Copy the API groups, resources, verbs, and resource names to your manifest, similar to the following example:
 +
@@ -260,9 +260,9 @@ rules:
 # ...
 ----
 
-. Search for the `services` and `configmaps` values in the `rules.resources` field in the extension's CSV file.
+. Search the bundle manifests for `Service` and `ConfigMap` resources that the extension requires.
 
-** Copy the API groups, resources, verbs, and resource names to your manifest, similar to the following example:
+** Add permissions for these resources to your manifest, similar to the following example:
 +
 [source,yaml]
 ----

modules/olmv1-creating-a-namespace.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * extensions/ce/managing-ce.adoc
+// * extensions/ce/granting-ce-permissions.adoc
 
 :_mod-docs-content-type: PROCEDURE
 

modules/olmv1-creating-a-service-account.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * extensions/ce/managing-ce.adoc
+// * extensions/ce/granting-ce-permissions.adoc
 
 :_mod-docs-content-type: PROCEDURE
 

modules/olmv1-downloading-bundle-manifests.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * extensions/ce/managing-ce.adoc
+// * extensions/ce/granting-ce-permissions.adoc
 
 :_mod-docs-content-type: PROCEDURE
 

modules/olmv1-example-pipelines-operator-cluster-role.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * extensions/ce/managing-ce.adoc
+// * extensions/ce/granting-ce-permissions.adoc
 
 :_mod-docs-content-type: REFERENCE
 

modules/olmv1-installing-an-operator-in-a-specific-namespace.adoc

@@ -18,7 +18,7 @@ include::snippets/technology-preview.adoc[]
 
 * You have access to an {product-title} cluster using an account with `cluster-admin` permissions.
 * You have enabled the `TechPreviewNoUpgrade` feature set on the cluster.
-* You have created a service account and assigned enough role-based access controls (RBAC) to install, update, and manage the extension. For more information, see "Cluster extension permissions".
+* You have granted the required permissions for cluster extensions. For more information, see "Granting permissions for cluster extensions".
 * You have verified the supported install modes for the extension and determined the required `watchNamespace` configuration.
 
 .Procedure

modules/olmv1-installing-an-operator.adoc

@@ -13,7 +13,7 @@ include::snippets/olmv1-cli-only.adoc[]
 
 .Prerequisites
 
-* You have created a service account and assigned enough role-based access controls (RBAC) to install, update, and manage the extension that you want to install. For more information, see "Cluster extension permissions".
+* You have granted the required permissions for cluster extensions. For more information, see "Granting permissions for cluster extensions".
 
 .Procedure
 
@@ -97,7 +97,7 @@ items:
   metadata:
     annotations:
       kubectl.kubernetes.io/last-applied-configuration: |
-        {"apiVersion":"olm.operatorframework.io/v1","kind":"ClusterExtension","metadata":{"annotations":{},"name":"pipes"},"spec":{"namespace":"pipelines","serviceAccount":{"name":"pipelines-installer"},"source":{"catalog":{"packageName":"openshift-pipelines-operator-rh","version":"1.14.x"},"sourceType":"Catalog"}}}
+        {"apiVersion":"olm.operatorframework.io/v1","kind":"ClusterExtension","metadata":{"annotations":{},"name":"pipelines-operator"},"spec":{"namespace":"pipelines","serviceAccount":{"name":"pipelines-installer"},"source":{"catalog":{"packageName":"openshift-pipelines-operator-rh","version":"1.14.x"},"sourceType":"Catalog"}}}
     creationTimestamp: "2025-02-18T21:48:13Z"
     finalizers:
     - olm.operatorframework.io/cleanup-unpack-cache

modules/olmv1-manual-cluster-role-scoping.adoc

@@ -0,0 +1,28 @@
+// Module included in the following assemblies:
+//
+// * extensions/ce/granting-ce-permissions.adoc
+
+:_mod-docs-content-type: CONCEPT
+
+[id="olmv1-manual-cluster-role-scoping_{context}"]
+= Manual cluster role scoping
+
+[role="_abstract"]
+You can manually define role-based access controls (RBAC) by inspecting extension bundles. By using this approach, you can define RBAC tailored to specific Operators.
+
+Manual scoping provides fine-grained security controls but requires maintaining permissions when requirements change, such as updating an Operator.
+
+[id="understanding-bundle-manifests_{context}"]
+== Understanding bundle manifests
+
+Extension bundles contain the manifests and metadata that define an Operator. The cluster service version (CSV) within the bundle declares the permissions required for the Operator to function. You can inspect these manifests to create cluster roles and roles that grant only the specific permissions an Operator needs.
+
+The manual scoping process involves the following tasks:
+
+* Download bundle manifests from the catalog
+* Identify custom resource definitions the Operator manages
+* Extract required permissions from the CSV
+* Create cluster roles and roles with the minimum required permissions
+* Create cluster role bindings and role bindings to grant these permissions to the service account
+
+When updating Operators, you must verify if the new version requires any new permissions.

modules/olmv1-required-rbac-to-install-and-manage-extension-resources.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * extensions/ce/managing-ce.adoc
+// * extensions/ce/granting-ce-permissions.adoc
 
 :_mod-docs-content-type: REFERENCE
 

modules/olmv1-updating-an-operator.adoc

@@ -112,7 +112,7 @@ items:
   metadata:
     annotations:
       kubectl.kubernetes.io/last-applied-configuration: |
-        {"apiVersion":"olm.operatorframework.io/v1","kind":"ClusterExtension","metadata":{"annotations":{},"name":"pipes"},"spec":{"namespace":"pipelines","serviceAccount":{"name":"pipelines-installer"},"source":{"catalog":{"packageName":"openshift-pipelines-operator-rh","version":"1.14.x"},"sourceType":"Catalog"}}}
+        {"apiVersion":"olm.operatorframework.io/v1","kind":"ClusterExtension","metadata":{"annotations":{},"name":"pipelines-operator"},"spec":{"namespace":"pipelines","serviceAccount":{"name":"pipelines-installer"},"source":{"catalog":{"packageName":"openshift-pipelines-operator-rh","version":"1.14.x"},"sourceType":"Catalog"}}}
     creationTimestamp: "2025-02-18T21:48:13Z"
     finalizers:
     - olm.operatorframework.io/cleanup-unpack-cache
@@ -302,13 +302,13 @@ kind: ClusterExtension
 metadata:
   annotations:
     kubectl.kubernetes.io/last-applied-configuration: |
-      {"apiVersion":"olm.operatorframework.io/v1","kind":"ClusterExtension","metadata":{"annotations":{},"name":"pipes"},"spec":{"namespace":"pipelines","serviceAccount":{"name":"pipelines-installer"},"source":{"catalog":{"packageName":"openshift-pipelines-operator-rh","version":"\u003c1.16"},"sourceType":"Catalog"}}}
+      {"apiVersion":"olm.operatorframework.io/v1","kind":"ClusterExtension","metadata":{"annotations":{},"name":"pipelines-operator"},"spec":{"namespace":"pipelines","serviceAccount":{"name":"pipelines-installer"},"source":{"catalog":{"packageName":"openshift-pipelines-operator-rh","version":"\u003c1.16"},"sourceType":"Catalog"}}}
   creationTimestamp: "2025-02-18T21:48:13Z"
   finalizers:
   - olm.operatorframework.io/cleanup-unpack-cache
   - olm.operatorframework.io/cleanup-contentmanager-cache
   generation: 2
-  name: pipes
+  name: pipelines-operator
   resourceVersion: "90693"
   uid: e18b13fb-a96d-436f-be75-a9a0f2b07993
 spec:
@@ -386,13 +386,13 @@ kind: ClusterExtension
 metadata:
   annotations:
     kubectl.kubernetes.io/last-applied-configuration: |
-      {"apiVersion":"olm.operatorframework.io/v1","kind":"ClusterExtension","metadata":{"annotations":{},"name":"pipes"},"spec":{"namespace":"pipelines","serviceAccount":{"name":"pipelines-installer"},"source":{"catalog":{"packageName":"openshift-pipelines-operator-rh","version":"9.x"},"sourceType":"Catalog"}}}
+      {"apiVersion":"olm.operatorframework.io/v1","kind":"ClusterExtension","metadata":{"annotations":{},"name":"pipelines-operator"},"spec":{"namespace":"pipelines","serviceAccount":{"name":"pipelines-installer"},"source":{"catalog":{"packageName":"openshift-pipelines-operator-rh","version":"9.x"},"sourceType":"Catalog"}}}
   creationTimestamp: "2025-02-18T21:48:13Z"
   finalizers:
   - olm.operatorframework.io/cleanup-unpack-cache
   - olm.operatorframework.io/cleanup-contentmanager-cache
   generation: 3
-  name: pipes
+  name: pipelines-operator
   resourceVersion: "93334"
   uid: e18b13fb-a96d-436f-be75-a9a0f2b07993
 spec:

snippets/example-pipelines-installer-clusterrole.yaml

@@ -12,7 +12,7 @@ rules:
   - update
   # Scoped to the name of the ClusterExtension
   resourceNames:
-  - pipes # the value from <metadata.name> from the extension's custom resource (CR)
+  - pipelines-operator # the value from <metadata.name> from the extension's custom resource (CR)
 # ClusterRoles and ClusterRoleBindings for the controllers of the extension
 - apiGroups:
   - rbac.authorization.k8s.io

snippets/olmv1-manual-rbac-scoping-admonition.adoc

@@ -7,5 +7,6 @@
 
 [IMPORTANT]
 ====
-To simply the following procedure and improve readability, the following example manifest uses permissions that are scoped to the cluster. You can further restrict some of the permissions by scoping them to the namespace of the extension instead of the cluster.
+* You must include delete permissions for all resources created by the bundle. Without delete permissions, Operators cannot remove their resources during uninstallation.
+* The following example manifest uses permissions that are scoped to the cluster. You can further restrict some of the permissions by scoping them to the namespace of the extension instead of the cluster.
 ====