diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index de9aadeb4965..a184c72cbe17 100644 --- a/_topic_maps/_topic_map.yml +++ b/_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 diff --git a/extensions/ce/granting-ce-permissions.adoc b/extensions/ce/granting-ce-permissions.adoc new file mode 100644 index 000000000000..4050bd341f47 --- /dev/null +++ b/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] diff --git a/extensions/ce/managing-ce.adoc b/extensions/ce/managing-ce.adoc index d21a8fc1fb34..1d84a7e1c7c5 100644 --- a/extensions/ce/managing-ce.adoc +++ b/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] diff --git a/extensions/ce/user-access-resources.adoc b/extensions/ce/user-access-resources.adoc index 656bdc5c79fe..ed057499842c 100644 --- a/extensions/ce/user-access-resources.adoc +++ b/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] diff --git a/modules/olmv1-cluster-extension-permissions.adoc b/modules/olmv1-cluster-extension-permissions.adoc index 60e655779e02..7f63dee763a4 100644 --- a/modules/olmv1-cluster-extension-permissions.adoc +++ b/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. diff --git a/modules/olmv1-creating-a-cluster-role-binding.adoc b/modules/olmv1-creating-a-cluster-role-binding.adoc index be359b6b762b..5a05dd2595d2 100644 --- a/modules/olmv1-creating-a-cluster-role-binding.adoc +++ b/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 diff --git a/modules/olmv1-creating-a-cluster-role.adoc b/modules/olmv1-creating-a-cluster-role.adoc index de0c403d1e82..00d663c2064a 100644 --- a/modules/olmv1-creating-a-cluster-role.adoc +++ b/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: `.`. 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] ---- diff --git a/modules/olmv1-creating-a-namespace.adoc b/modules/olmv1-creating-a-namespace.adoc index cf79788ef5fc..88e69214842f 100644 --- a/modules/olmv1-creating-a-namespace.adoc +++ b/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 diff --git a/modules/olmv1-creating-a-service-account.adoc b/modules/olmv1-creating-a-service-account.adoc index d8d3868b1fab..0e78d0107534 100644 --- a/modules/olmv1-creating-a-service-account.adoc +++ b/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 diff --git a/modules/olmv1-downloading-bundle-manifests.adoc b/modules/olmv1-downloading-bundle-manifests.adoc index 1d35b4c687ab..65de5fa2dfb4 100644 --- a/modules/olmv1-downloading-bundle-manifests.adoc +++ b/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 diff --git a/modules/olmv1-example-pipelines-operator-cluster-role.adoc b/modules/olmv1-example-pipelines-operator-cluster-role.adoc index 24b83911da2d..cb69860143e2 100644 --- a/modules/olmv1-example-pipelines-operator-cluster-role.adoc +++ b/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 diff --git a/modules/olmv1-installing-an-operator-in-a-specific-namespace.adoc b/modules/olmv1-installing-an-operator-in-a-specific-namespace.adoc index 5e6f2fd38e6c..4fb235e1811a 100644 --- a/modules/olmv1-installing-an-operator-in-a-specific-namespace.adoc +++ b/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 diff --git a/modules/olmv1-installing-an-operator.adoc b/modules/olmv1-installing-an-operator.adoc index 4e5f2f8d8f67..09fd1585bae6 100644 --- a/modules/olmv1-installing-an-operator.adoc +++ b/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 diff --git a/modules/olmv1-manual-cluster-role-scoping.adoc b/modules/olmv1-manual-cluster-role-scoping.adoc new file mode 100644 index 000000000000..c80dadd50120 --- /dev/null +++ b/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. diff --git a/modules/olmv1-required-rbac-to-install-and-manage-extension-resources.adoc b/modules/olmv1-required-rbac-to-install-and-manage-extension-resources.adoc index e368e7c34586..9b37e70071ac 100644 --- a/modules/olmv1-required-rbac-to-install-and-manage-extension-resources.adoc +++ b/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 diff --git a/modules/olmv1-updating-an-operator.adoc b/modules/olmv1-updating-an-operator.adoc index aa293e47eb56..1f1ef175cdca 100644 --- a/modules/olmv1-updating-an-operator.adoc +++ b/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: diff --git a/snippets/example-pipelines-installer-clusterrole.yaml b/snippets/example-pipelines-installer-clusterrole.yaml index 0b7b2dda35c3..2f8ddebe11a0 100644 --- a/snippets/example-pipelines-installer-clusterrole.yaml +++ b/snippets/example-pipelines-installer-clusterrole.yaml @@ -12,7 +12,7 @@ rules: - update # Scoped to the name of the ClusterExtension resourceNames: - - pipes # the value from from the extension's custom resource (CR) + - pipelines-operator # the value from from the extension's custom resource (CR) # ClusterRoles and ClusterRoleBindings for the controllers of the extension - apiGroups: - rbac.authorization.k8s.io diff --git a/snippets/olmv1-manual-rbac-scoping-admonition.adoc b/snippets/olmv1-manual-rbac-scoping-admonition.adoc index 09e40d7cb6f9..53d430c3c5f8 100644 --- a/snippets/olmv1-manual-rbac-scoping-admonition.adoc +++ b/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. ====