OSDOCS#14594: OLMv1 RBAC preflight check (TP)

Author: michaelryanpeter

extensions/ce/managing-ce.adoc

@@ -37,6 +37,8 @@ include::modules/olmv1-installing-an-operator-in-a-specific-namespace.adoc[level
 * xref:../../extensions/ce/update-paths.adoc#olmv1-about-target-versions_update-paths[Example custom resources (CRs) that specify a target version]
 * xref:../../extensions/ce/update-paths.adoc#olmv1-version-range-support_update-paths[Support for version ranges]
 
+include::modules/olmv1-troubleshooting-rbac-errors-with-preflight-check.adoc[leveloffset=+1]
+
 include::modules/olmv1-updating-an-operator.adoc[leveloffset=+1]
 
 [role="_additional-resources"]

modules/olmv1-troubleshooting-rbac-errors-with-preflight-check.adoc

@@ -0,0 +1,69 @@
+// Module included in the following assemblies:
+//
+// * extensions/ce/olmv1-installing-an-operator-from-a-catalog.adoc
+
+:_mod-docs-content-type: REFERENCE
+
+[id="olmv1-troubleshooting-rbac-errors-with-preflight-check_{context}"]
+= Preflight permissions check for cluster extensions (Technology Preview)
+
+When you try to install an extension, the Operator Controller performs a dry run of the installation process. This dry run verifies that the specified service account can perform all the actions required to install the extension. This includes creating all the Kubernetes objects in the bundle and the role-based access control (RBAC) rules for the roles and bindings defined by the bundle.
+
+:FeatureName: The preflight permissions check for cluster extensions
+include::snippets/technology-preview.adoc[]
+
+If the service account is missing any required RBAC rules, the preflight check fails before the actual installation proceeds. If the preflight check fails, the Operator Controller reports the errors in the status conditions of the extension and in the logs of the Operator Controller.
+
+To proceed with the installation, update the roles and bindings to grant the missing permissions to the service account and apply the changes. If there are no errors, the Operator Controller reconciles the updated permissions and completes the installation.
+
+[id="olmv1-preflight-permissions-check-output_{context}"]
+== Example report from the preflight permissions check
+
+The following report indicates that the service account requires the following missing permissions:
+
+* RBAC rules to perform `list` and `watch` actions for the `services` resource in the core API group for the entire cluster
+* RBAC rules to perform `create` actions for `deployments` resources in the `apps` API group for the `pipelines` namespace
+
+You can access the reports from the preflight permissions check in the status conditions of the cluster extension. The `oc describe clusterextension` command prints information about a cluster extension, including the status conditions.
+
+.Example command
+[source,terminal]
+----
+$ oc describe clusterextension <extension_name>
+----
+
+.Example report
+[source,text]
+----
+apiVersion: v1
+items:
+- apiVersion: olm.operatorframework.io/v1
+  kind: ClusterExtension
+...
+Conditions:
+  Type:    Progressing
+  Status:  False
+  Reason:  Retrying
+  Message: pre-authorization failed: service account requires the following permissions to manage cluster extension:
+           Namespace:"" APIGroups:[] Resources:[services] Verbs:[list,watch]
+           Namespace:"pipelines" APIGroups:["apps"] Resources:[deployments] Verbs:[create]
+----
+
+`Namespace`:: Specifies the scope of the required RBAC rules at the namespace level, for example the `pipelines` namespace. An empty namespace value, `""`, indicates that you must scope the permission to the cluster.
+
+`APIGroups`:: Specifies the name of the API group the required permissions apply to. An empty value in the API group, `[]`, indicates the permissions apply to the core API group. For example, services, secrets, and config maps are all core resources.
++
+If a resource belongs to a named API group, the report lists the name in between the brackets. For example, the value of `APIGroups:[apps]` indicates the extension requires RBAC rules to act on resources in the `apps` API group.
+
+`Resources`:: Specifies the resource types that require permissions. For example, services, secrets, and custom resource definitions are common resource types.
+
+`Verbs`:: Specifies the actions, or _verbs_, that the service account needs permission to perform. If the report lists several verbs, all of the listed verbs require RBAC rules.
+
+[id="olmv1-common-rbac-errors_{context}"]
+== Common permission errors
+
+Missing verbs:: The service account does not have permission to perform a required action. To resolve this issue, update or create a role and binding to grant the necessary permissions. Roles and role bindings define resource permissions for a namespace. Cluster roles and cluster role bindings define resource permissions for the cluster.
+
+Privilege escalation:: The service account does not have enough permission to create a role or cluster role that the extension needs. When this happens, the preflight check reports the verbs as missing to prevent privilege escalation. To resolve this issue, grant enough permission to the service account so that it can create the roles.
+
+Missing role references:: The extension references a role or cluster role that the Operator Controller cannot find. When this happens, the preflight check lists the missing role and reports an `authorization evalutation error`. To resolve the issue, create or update the roles and cluster roles to ensure that all role references exist.