diff --git a/extensions/ce/managing-ce.adoc b/extensions/ce/managing-ce.adoc index 2c6f51612f..66cdc5959d 100644 --- a/extensions/ce/managing-ce.adoc +++ b/extensions/ce/managing-ce.adoc @@ -26,11 +26,13 @@ include::modules/olmv1-supported-extensions.adoc[leveloffset=+1] include::modules/olmv1-finding-operators-to-install.adoc[leveloffset=+1] include::modules/olmv1-catalog-queries.adoc[leveloffset=+2] +include::modules/olmv1-creating-a-service-account.adoc[leveloffset=+1] include::modules/olmv1-installing-an-operator.adoc[leveloffset=+1] [role="_additional-resources"] .Additional resources * xref:../../extensions/ce/managing-ce.adoc#olmv1-supported-extensions_managing-ce[Supported extensions] +* xref:../../extensions/ce/managing-ce.adoc#olmv1-creating-a-service-account_managing-ce[Creating a service account] * xref:../../extensions/ce/upgrade-edges.adoc#olmv1-about-target-versions_upgrade-edges[Example custom resources (CRs) that specify a target version] * xref:../../extensions/ce/upgrade-edges.adoc#olmv1-version-range-support_upgrade-edges[Support for version ranges] diff --git a/modules/olmv1-creating-a-service-account.adoc b/modules/olmv1-creating-a-service-account.adoc new file mode 100644 index 0000000000..dc48fb4a8b --- /dev/null +++ b/modules/olmv1-creating-a-service-account.adoc @@ -0,0 +1,138 @@ +// Module included in the following assemblies: +// +// * extensions/ce/managing-ce.adoc + +:_mod-docs-content-type: PROCEDURE + +[id="olmv1-creating-a-service-account_{context}"] += Creating a service account to manage cluster extensions + +Unlike {olmv0-first}, {olmv1} does not have permissions to install, update, and manage cluster extensions. Cluster administrators must create a service account and assign the role-based access controls (RBAC) required to install, update, and manage cluster extensions. + +[IMPORTANT] +==== +include::snippets/olmv1-known-issue-service-accounts.adoc[] +==== + +.Prerequisites + +* Access to an {product-title} cluster using an account with `cluster-admin` permissions. + +.Procedure + +. Create a service account, similar to the following example: ++ +[source,yaml] +---- +apiVersion: v1 +kind: ServiceAccount +metadata: + name: -installer + namespace: +---- ++ +.Example `extension-service-account.yaml` file +[%collapsible] +==== +[source,yaml] +---- +apiVersion: v1 +kind: ServiceAccount +metadata: + name: pipelines-installer + namespace: pipelines +---- +==== + +. Apply the service account by running the following command: ++ +[source,terminal] +---- +$ oc apply -f extension-service-account.yaml +---- +. Create a cluster role and assign RBAC, similar to the following example: ++ +[WARNING] +==== +The following cluster role does not follow the principle of least privilege. This cluster role is intended for testing purposes only. Do not use it on production clusters. +==== ++ +[source,yaml] +---- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: -installer-clusterrole +rules: +- apiGroups: ["*"] + resources: ["*"] + verbs: ["*"] +---- ++ +.Example `pipelines-cluster-role.yaml` file +[%collapsible] +==== +[source,yaml] +---- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: pipelines-installer-clusterrole +rules: +- apiGroups: ["*"] + resources: ["*"] + verbs: ["*"] +---- +==== + +. Add the cluster role to the cluster by running the following command: ++ +[source,terminal] +---- +$ oc apply -f pipelines-role.yaml +---- + +. Bind the permissions granted by the cluster role to the service account by creating a cluster role binding, similar to the following example: ++ +[source,yaml] +---- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: -installer-binding +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: -installer-clusterrole +subjects: +- kind: ServiceAccount + name: -installer + namespace: +---- ++ +.Example `pipelines-cluster-role-binding.yaml` file +[%collapsible] +==== +[source,yaml] +---- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: pipelines-installer-binding +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: pipelines-installer-clusterrole +subjects: +- kind: ServiceAccount + name: pipelines-installer + namespace: pipelines +---- +==== + +. Apply the cluster role binding by running the following command: ++ +[source,terminal] +---- +$ oc apply -f pipelines-cluster-role-binding.yaml +---- diff --git a/modules/olmv1-installing-an-operator.adoc b/modules/olmv1-installing-an-operator.adoc index 54cbf29b93..a3d22c94ff 100644 --- a/modules/olmv1-installing-an-operator.adoc +++ b/modules/olmv1-installing-an-operator.adoc @@ -20,6 +20,7 @@ include::snippets/olmv1-known-issue-private-registries.adoc[] * You have added a catalog to your cluster. * You have downloaded a local copy of the catalog file. * You have installed the `jq` CLI tool. +* You have created a service account and assigned enough role-based access controls (RBAC) to install, update, and manage the extension you want to install. For more information, see _Creating a service account_. .Procedure @@ -120,13 +121,16 @@ metadata: spec: packageName: openshift-pipelines-operator-rh installNamespace: + serviceAccount: + name: channel: version: "" ---- + where: + -``:: Specifies the namespace where you want the bundle installed, such as `openshift-operators` or `my-extension`. Extensions are still cluster-scoped and might contain resources that are installed in different namespaces. +``:: 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. +``:: Specifies the name of the service account you created to install, update, and manage your extension. ``:: Optional: Specifies the channel, such as `pipelines-1.11` or `latest`, for the package you want to install or update. ``:: Optional: Specifies the version or version range, such as `1.11.1`, `1.12.x`, or `>=1.12.1`, 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". + @@ -168,16 +172,20 @@ items: metadata: annotations: kubectl.kubernetes.io/last-applied-configuration: | - {"apiVersion":"olm.operatorframework.io/v1alpha1","kind":"ClusterExtension","metadata":{"annotations":{},"name":"pipelines-operator"},"spec":{"channel":"latest","installNamespace":"openshift-operators","packageName":"openshift-pipelines-operator-rh","pollInterval":"30m"}} + {"apiVersion":"olm.operatorframework.io/v1alpha1","kind":"ClusterExtension","metadata":{"annotations":{},"name":"pipelines-operator"},"spec":{"channel":"latest","installNamespace":"pipelines","packageName":"openshift-pipelines-operator-rh","serviceAccount":{"name":"pipelines-installer"},"pollInterval":"30m"}} creationTimestamp: "2024-06-10T17:50:51Z" + finalizers: + - olm.operatorframework.io/cleanup-unpack-cache generation: 1 name: pipelines-operator resourceVersion: "53324" uid: c54237be-cde4-46d4-9b31-d0ec6acc19bf spec: channel: latest - installNamespace: openshift-operators + installNamespace: pipelines packageName: openshift-pipelines-operator-rh + serviceAccount: + name: pipelines-installer upgradeConstraintPolicy: Enforce status: conditions: @@ -217,15 +225,18 @@ items: reason: Deprecated status: "False" type: BundleDeprecated + - lastTransitionTime: "2024-06-10T17:50:58Z" + message: 'unpack successful: + observedGeneration: 1 + reason: UnpackSuccess + status: "True" + type: Unpacked installedBundle: name: openshift-pipelines-operator-rh.v1.14.4 version: 1.14.4 resolvedBundle: name: openshift-pipelines-operator-rh.v1.14.4 version: 1.14.4 -kind: List -metadata: - resourceVersion: "" ---- where: diff --git a/snippets/olmv1-known-issue-service-accounts.adoc b/snippets/olmv1-known-issue-service-accounts.adoc new file mode 100644 index 0000000000..7f7803d5b2 --- /dev/null +++ b/snippets/olmv1-known-issue-service-accounts.adoc @@ -0,0 +1,14 @@ +// Text snippet included in the following modules: +// +// * modules/olmv1-installing-an-operator.adoc +// * release_notes/ocp-4-17-release-notes.adoc (enterprise-4.17 branch only) + +:_mod-docs-content-type: SNIPPET + +There is a known issue in {olmv1}. If you do not assign the correct role-based access controls (RBAC) to an extension's service account, {olmv1} gets stuck and reconciliation stops. + +Currently, {olmv1} does not have tools to help extension administrators find the correct RBAC for a service account. + +Because {olmv1} is a Technology Preview feature and must not be used on production clusters, you can avoid this issue by using the more permissive RBAC included in the documentation. + +This RBAC is intended for testing purposes only. Do not use it on production clusters.