Merge pull request #51409 from adellape/global_scoping

Author: adellape

modules/olm-catalogsource.adoc

@@ -58,7 +58,7 @@ status:
     serviceNamespace: {global_ns}
 ----
 <1> Name for the `CatalogSource` object. This value is also used as part of the name for the related pod that is created in the requested namespace.
-<2> Namespace to create the catalog available. To make the catalog available cluster-wide in all namespaces, set this value to `{global_ns}`. The default Red Hat-provided catalog sources also use the `{global_ns}` namespace. Otherwise, set the value to a specific namespace to make the Operator only available in that namespace.
+<2> Namespace to create the catalog in. To make the catalog available cluster-wide in all namespaces, set this value to `{global_ns}`. The default Red Hat-provided catalog sources also use the `{global_ns}` namespace. Otherwise, set the value to a specific namespace to make the Operator only available in that namespace.
 <3> Optional: To avoid cluster upgrades potentially leaving Operator installations in an unsupported state or without a continued update path, you can enable automatically changing your Operator catalog's index image version as part of cluster upgrades.
 +
 Set the `olm.catalogImageTemplate` annotation to your index image name and use one or more of the Kubernetes cluster version variables as shown when constructing the template for the image tag. The annotation overwrites the `spec.image` field at run time. See the "Image template for custom catalog sources" section for more details.

modules/olm-policy-catalog-access.adoc

@@ -0,0 +1,14 @@
+// Module included in the following assemblies:
+//
+// * operators/admin/olm-creating-policy.adoc
+
+:_content-type: CONCEPT
+[id="olm-policy-catalog-access_{context}"]
+= Operator catalog access control
+
+When an Operator catalog is created in the global catalog namespace `openshift-marketplace`, the catalog's Operators are made available cluster-wide to all namespaces. A catalog created in other namespaces only makes its Operators available in that same namespace of the catalog.
+
+On clusters where non-cluster administrator users have been delegated Operator installation privileges, cluster administrators might want to further control or restrict the set of Operators those users are allowed to install. This can be achieved with the following actions:
+
+. Disable all of the default global catalogs.
+. Enable custom, curated catalogs in the same namespace where the relevant Operator groups have been pre-installed.

modules/olm-policy-understanding.adoc

@@ -6,10 +6,21 @@
 [id="olm-policy-understanding_{context}"]
 = Understanding Operator installation policy
 
-Using Operator Lifecycle Manager (OLM), cluster administrators can choose to specify a service account for an Operator group so that all Operators associated with the group are deployed and run against the privileges granted to the service account.
+Operators can require wide privileges to run, and the required privileges can change between versions. Operator Lifecycle Manager (OLM) runs with `cluster-admin` privileges. By default, Operator authors can specify any set of permissions in the cluster service version (CSV), and OLM consequently grants it to the Operator.
 
-The `APIService` and `CustomResourceDefinition` resources are always created by OLM using the `cluster-admin` role. A service account associated with an Operator group should never be granted privileges to write these resources.
+To ensure that an Operator cannot achieve cluster-scoped privileges and that users cannot escalate privileges using OLM, Cluster administrators can manually audit Operators before they are added to the cluster. Cluster administrators are also provided tools for determining and constraining which actions are allowed during an Operator installation or upgrade using service accounts.
 
-If the specified service account does not have adequate permissions for an Operator that is being installed or upgraded, useful and contextual information is added to the status of the respective resource(s) so that it is easy for the cluster administrator to troubleshoot and resolve the issue.
+Cluster administrators can associate an Operator group with a service account that has a set of privileges granted to it. The service account sets policy on Operators to ensure they only run within predetermined boundaries by using role-based access control (RBAC) rules. As a result, the Operator is unable to do anything that is not explicitly permitted by those rules.
 
-Any Operator tied to this Operator group is now confined to the permissions granted to the specified service account. If the Operator asks for permissions that are outside the scope of the service account, the install fails with appropriate errors.
+By employing Operator groups, users with enough privileges can install Operators with a limited scope. As a result, more of the Operator Framework tools can safely be made available to more users, providing a richer experience for building applications with Operators.
+
+[NOTE]
+====
+Role-based access control (RBAC) for `Subscription` objects is automatically granted to every user with the `edit` or `admin` role in a namespace. However, RBAC does not exist on `OperatorGroup` objects; this absence is what prevents regular users from installing Operators. Pre-installing Operator groups is effectively what gives installation privileges.
+====
+
+Keep the following points in mind when associating an Operator group with a service account:
+
+* The `APIService` and `CustomResourceDefinition` resources are always created by OLM using the `cluster-admin` role. A service account associated with an Operator group should never be granted privileges to write these resources.
+
+* Any Operator tied to this Operator group is now confined to the permissions granted to the specified service account. If the Operator asks for permissions that are outside the scope of the service account, the install fails with appropriate errors so the cluster administrator can troubleshoot and resolve the issue.

modules/olm-rh-catalogs.adoc

@@ -3,11 +3,19 @@
 // * operators/understanding/olm-rh-catalogs.adoc
 
 :tag: v{product-version}
+ifdef::openshift-origin[]
+:global_ns: olm
+endif::[]
+ifndef::openshift-origin[]
+:global_ns: openshift-marketplace
+endif::[]
 
 :_content-type: CONCEPT
 [id="olm-rh-catalogs_{context}"]
 = About Red Hat-provided Operator catalogs
 
+The Red Hat-provided catalog sources are installed by default in the `{global_ns}` namespace, which makes the catalogs available cluster-wide in all namespaces.
+
 The following Operator catalogs are distributed by Red Hat:
 
 [cols="20%,55%,25%",options="header"]

operators/admin/olm-creating-policy.adoc

@@ -6,13 +6,12 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-Operators can require wide privileges to run, and the required privileges can change between versions. Operator Lifecycle Manager (OLM) runs with `cluster-admin` privileges. By default, Operator authors can specify any set of permissions in the cluster service version (CSV) and OLM will consequently grant it to the Operator.
+Cluster administrators can use _Operator groups_ to allow regular users to install Operators.
 
-Cluster administrators should take measures to ensure that an Operator cannot achieve cluster-scoped privileges and that users cannot escalate privileges using OLM. One method for locking this down requires cluster administrators auditing Operators before they are added to the cluster. Cluster administrators are also provided tools for determining and constraining which actions are allowed during an Operator installation or upgrade using service accounts.
+[role="_additional-resources"]
+.Additional resources
 
-By associating an _Operator group_ with a service account that has a set of privileges granted to it, cluster administrators can set policy on Operators to ensure they operate only within predetermined boundaries using RBAC rules. The Operator is unable to do anything that is not explicitly permitted by those rules.
-
-This self-sufficient, limited scope installation of Operators by non-cluster administrators means that more of the Operator Framework tools can safely be made available to more users, providing a richer experience for building applications with Operators.
+* xref:../../operators/understanding/olm/olm-understanding-operatorgroups.adoc#olm-understanding-operatorgroups[Operator groups]
 
 include::modules/olm-policy-understanding.adoc[leveloffset=+1]
 include::modules/olm-policy-scenarios.adoc[leveloffset=+2]
@@ -21,4 +20,11 @@ include::modules/olm-policy-workflow.adoc[leveloffset=+2]
 include::modules/olm-policy-scoping-operator-install.adoc[leveloffset=+1]
 include::modules/olm-policy-fine-grained-permissions.adoc[leveloffset=+2]
 
+include::modules/olm-policy-catalog-access.adoc[leveloffset=+1]
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../operators/admin/olm-managing-custom-catalogs.adoc#olm-restricted-networks-operatorhub_olm-managing-custom-catalogs[Disabling the default OperatorHub sources]
+* xref:../../operators/admin/olm-managing-custom-catalogs.adoc#olm-creating-catalog-from-index_olm-managing-custom-catalogs[Adding a catalog source to a cluster]
+
 include::modules/olm-policy-troubleshooting.adoc[leveloffset=+1]