Managing Cluster Extensions: Minimalism and readability fixes

extensions/ce/managing-ce.adoc

@@ -6,9 +6,7 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-After a catalog has been added to your cluster, you have access to the versions, patches, and over-the-air updates of the extensions and Operators that are published to the catalog.
-
-You can use custom resources (CRs) to manage extensions declaratively from the CLI.
+As a cluster administrator, you can manage cluster extensions declaratively. You can install, update, and delete them using custom resources and CLI tools.
 
 include::snippets/olmv1-cli-only.adoc[]
 

modules/olmv1-cluster-extension-permissions.adoc

@@ -9,12 +9,14 @@
 
 In {olmv0-first}, a single service account with cluster administrator privileges manages all cluster extensions.
 
-{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.
+In {olmv1}, each cluster extension uses the service account specified in the extension's custom resource (CR). Cluster administrators can create a service account for each extension. You can then assign only the permissions needed to install and manage that extension.
 
 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.
+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.
+
+Choose cluster or namespace scope based on your extension design.
 
 include::snippets/olmv1-manual-rbac-scoping-admonition.adoc[]
 
-If a new version of an installed extension requires additional permissions, {olmv1} halts the update process until a cluster administrator grants those permissions.
+{olmv1} halts updates if a new version needs more permissions. The update resumes when a cluster administrator grants those permissions.

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

@@ -7,11 +7,11 @@
 [id="olmv1-creating-a-cluster-role_{context}"]
 = Creating a cluster role for an extension
 
-You must review the `install.spec.clusterpermissions` stanza of the cluster service version (CSV) and the manifests of an extension carefully to define the required role-based access controls (RBAC) of the extension that you want to install. You must create a cluster role by copying the required RBAC from the CSV to the new manifest.
+Review the cluster service version (CSV) and extension manifests carefully. Look at the `install.spec.clusterpermissions` stanza to identify the required role-based access controls (RBAC). Create a cluster role by copying the required RBAC from the CSV to a new manifest.
 
 [TIP]
 ====
-If you want to test the process for installing and updating an extension in {olmv1}, you can use the following cluster role to grant cluster administrator permissions. This manifest is for testing purposes only. It should not be used in production clusters.
+If you want to test the process for installing and updating an extension in {olmv1}, you can use the following cluster role to grant cluster administrator permissions. This manifest is for testing purposes only. Do not use it in production clusters.
 
 [source,yaml]
 ----
@@ -125,7 +125,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.
+<2> Some resource names are generated by using the following format: `<package_name>.<hash>`. After you install the extension, look up the resource names. Find the names for cluster roles and cluster role bindings for the extension controller. 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.
 

modules/olmv1-deleting-an-operator.adoc

@@ -7,7 +7,7 @@
 [id="olmv1-deleting-an-operator_{context}"]
 = Deleting an Operator
 
-You can delete an Operator and its custom resource definitions (CRDs) by deleting the `ClusterExtension` custom resource (CR).
+Delete an Operator and its custom resource definitions (CRDs) by deleting the cluster extension custom resource (CR).
 
 .Prerequisites
 
@@ -46,7 +46,7 @@ $ oc get clusterextensions
 No resources found
 ----
 
-** Verify that the Operator's system namespace is deleted by running the following command:
+** Verify the namespace no longer exists by running the following command:
 +
 [source,terminal]
 ----

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

@@ -7,7 +7,7 @@
 [id="olmv1-example-cluster-role-pipelines_{context}"]
 = Example cluster role for the {pipelines-title} Operator
 
-See the following example for a complete cluster role manifest for the {pipelines-shortname} Operator.
+The following example shows a complete cluster role for the {pipelines-shortname} Operator.
 
 [source,yaml]
 ----

modules/olmv1-installing-an-operator.adoc

@@ -38,11 +38,11 @@ apiVersion: olm.operatorframework.io/v1
         version: <version_or_version_range> <4>
         upgradeConstraintPolicy: CatalogProvided <5>
 ----
-<1> Specifies the namespace where you want the bundle installed, such as `pipelines` or `my-extension`. Extensions are still cluster-scoped and might contain resources that are installed in different namespaces.
+<1> Specifies the namespace where you want the bundle installed, such as `pipelines` or `my-extension`. Extensions are cluster-scoped, but they might install resources in different namespaces.
 <2> Specifies the name of the service account you created to install, update, and manage your extension.
 <3> Optional: Specifies channel names as an array, such as `pipelines-1.14` or `latest`.
 <4> Optional: Specifies the version or version range, such as `1.14.0`, `1.14.x`, or `>=1.16`, of the package you want to install or update. For more information, see "Example custom resources (CRs) that specify a target version" and "Support for version ranges".
-<5> Optional: Specifies the upgrade constraint policy. If unspecified, the default setting is `CatalogProvided`. The `CatalogProvided` setting only updates if the new version satisfies the upgrade constraints set by the package author. To force an update or rollback, set the field to `SelfCertified`. For more information, see "Forcing an update or rollback".
+<5> Optional: Specifies the upgrade constraint policy. If unspecified, the default setting is `CatalogProvided`. The `CatalogProvided` setting only updates if the new version meets the upgrade constraints set by the package author. To force an update or rollback, set the field to `SelfCertified`. For more information, see "Forcing an update or rollback".
 
 .Example `pipelines-operator.yaml` CR
 [source,yaml]

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

@@ -7,24 +7,24 @@
 [id="olmv1-required-rbac-to-install-and-manage-extension-resources_{context}"]
 = Required permissions to install and manage a cluster extension
 
-You must inspect the manifests included in the bundle image of a cluster extension to assign the necessary permissions. The service account requires enough role-based access controls (RBAC) to create and manage the following resources.
+Inspect the bundle image manifests to determine what permissions you need to assign. The service account needs enough role-based access controls (RBAC) to create and manage the following resources.
 
 [IMPORTANT]
 ====
 Follow the principle of least privilege and scope permissions to specific resource names with the least RBAC required to run.
 ====
 
-Admission plugins:: Because {product-title} clusters use the `OwnerReferencesPermissionEnforcement` admission plugin, cluster extensions must have permissions to update the `blockOwnerDeletion` and `ownerReferences` finalizers.
+Admission plugins:: Cluster extensions need permissions to update the `blockOwnerDeletion` and `ownerReferences` finalizers. This requirement exists because {product-title} clusters use the `OwnerReferencesPermissionEnforcement` admission plugin.
 
 Cluster role and cluster role bindings for the controllers of the extension:: You must define RBAC so that the installation service account can create and manage cluster roles and cluster role bindings for the extension controllers.
 
 Cluster service version (CSV):: You must define RBAC for the resources defined in the CSV of the cluster extension.
 
-Cluster-scoped bundle resources:: You must define RBAC to create and manage any cluster-scoped resources included in the bundle. If the cluster-scoped resources matches another resource type, such as a `ClusterRole`, you can add the resource to the pre-existing rule under the `resources` or `resourceNames` field.
+Cluster-scoped bundle resources:: You must define RBAC to create and manage any cluster-scoped resources included in the bundle. If the cluster-scoped resource matches another resource type like `ClusterRole`, add it to the existing rule. You can place it under the `resources` or `resourceNames` field.
 
 Custom resource definitions (CRDs):: You must define RBAC so that the installation service account can create and manage the CRDs for the extension. Also, you must grant the service account for the controller of the extension the RBAC to manage its CRDs.
 
-Deployments:: You must define RBAC for the installation service account to create and manage the deployments needed by the extension controller, such as services and config maps.
+Deployments:: Define RBAC so that the installation service account can create and manage deployments, services, and config maps needed by the extension controller.
 
 Extension permissions:: You must include RBAC for the permissions and cluster permissions defined in the CSV. The installation service account needs the ability to grant these permissions to the extension controller, which needs these permissions to run.
 

modules/olmv1-updating-an-operator.adoc

@@ -87,7 +87,7 @@ $ opm render registry.redhat.io/redhat/redhat-operator-index:v{product-version}
 ----
 ====
 
-. Find out what version or channel is specified in your Operator or extension's CR by running the following command:
+. Discover what version or channel is specified in your Operator or extension's CR by running the following command:
 +
 [source,terminal]
 ----
@@ -244,7 +244,7 @@ spec:
       channels:
         - latest <1>
 ----
-<1> Installs the latest release that can be resolved from the specified channel. Updates to the channel are automatically installed. Enter values as an array.
+<1> Installs the latest release that can be resolved from the specified channel. Updates to the channel install automatically. Enter values as an array.
 
 ** If you want to specify a channel and version or version range, edit your CR similar to the following example:
 +