diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 6f1bc1f01d86..bbefef433269 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -1250,6 +1250,8 @@ Topics: File: persistent-storage-csi - Name: CSI inline ephemeral volumes File: ephemeral-storage-csi-inline + - Name: Shared Resource CSI Driver Operator + File: ephemeral-storage-shared-resource-csi-driver-operator - Name: CSI volume snapshots File: persistent-storage-csi-snapshots - Name: CSI volume cloning diff --git a/modules/builds-using-build-volumes.adoc b/modules/builds-using-build-volumes.adoc index a7f5fb89a00d..e12907e495eb 100644 --- a/modules/builds-using-build-volumes.adoc +++ b/modules/builds-using-build-volumes.adoc @@ -68,7 +68,7 @@ spec: [NOTE] ==== -The shared resource CSI driver is supported as **Tech Preview** only. +The Shared Resource CSI Driver is supported as a Technology Preview feature. ==== endif::dockerstrategy[] @@ -118,7 +118,7 @@ spec: [NOTE] ==== -The shared resource CSI driver is supported as **Tech Preview** only. +The Shared Resource CSI Driver is supported as a Technology Preview feature. ==== endif::sourcestrategy[] diff --git a/modules/ephemeral-storage-additional-details-about-volumeattributes-on-shared-resource-pod-volumes.adoc b/modules/ephemeral-storage-additional-details-about-volumeattributes-on-shared-resource-pod-volumes.adoc new file mode 100644 index 000000000000..071d522d529a --- /dev/null +++ b/modules/ephemeral-storage-additional-details-about-volumeattributes-on-shared-resource-pod-volumes.adoc @@ -0,0 +1,37 @@ +:_content-type: REFERENCE + +[id="ephemeral-storage-additional-details-about-volumeattributes-on-shared-resource-pod-volumes_{context}"] += Additional details about VolumeAttributes on shared resource pod volumes + +[role="_abstract"] +The following attributes affect shared resource pod volumes in various ways: + +* The `refreshResource` attribute in the `volumeAttributes` properties. +* The `refreshResources` attribute in the Shared Resource CSI Driver configuration. +* The `sharedSecret` and `sharedConfigMap` attributes in the `volumeAttributes` properties. + +== The `refreshResource` attribute + +The Shared Resource CSI Driver honors the `refreshResource` attribute in `volumeAttributes` properties of the volume. This attribute controls whether updates to the contents of the underlying `Secret` or `ConfigMap` object are copied to the volume *after* the volume is initially provisioned as part of pod startup. The default value of `refreshResource` is `true`, which means that the contents are updated. + +[IMPORTANT] +==== +If the Shared Resource CSI Driver configuration has disabled the refreshing of both the shared `SharedSecret` and `SharedConfigMap` custom resource (CR) instances, then the `refreshResource` attribute in the `volumeAttribute` properties has no effect. The intent of this attribute is to disable refresh for specific volume mounts when refresh is generally allowed. +==== + +== The `refreshResources` attribute + +You can use a global switch to enable or disable refreshing of shared resources. This switch is the `refreshResources` attribute in the `csi-driver-shared-resource-config` config map for the Shared Resource CSI Driver, which you can find in the `openshift-cluster-csi-drivers` namespace. If you set this `refreshResources` attribute to `false`, none of the `Secret` or `ConfigMap` object-related content stored in the volume is updated after the initial provisioning of the volume. + +[IMPORTANT] +==== +Using this Shared Resource CSI Driver configuration to disable refreshing affects all the cluster's volume mounts that use the Shared Resource CSI Driver, regardless of the `refreshResource` attribute in the `volumeAttributes` properties of any of those volumes. +==== + +== Validation of volumeAttributes before provisioning a shared resource volume for a pod + +In the `volumeAttributes` of a single volume, you must set either a `sharedSecret` or a `sharedConfigMap` attribute to the value of a `SharedSecret` or a `SharedConfigMap` CS instance. Otherwise, when the volume is provisioned during pod startup, a validation checks the `volumeAttributes` of that volume and returns an error to the kubelet under the following conditions: + +* Both `sharedSecret` and `sharedConfigMap` attributes have specified values. +* Neither `sharedSecret` nor `sharedConfigMap` attributes have specified values. +* The value of the `sharedSecret` or `sharedConfigMap` attribute does not correspond to the name of a `SharedSecret` or `SharedConfigMap` CR instance on the cluster. diff --git a/modules/ephemeral-storage-additional-support-limitations-for-shared-resource-csi-driver.adoc b/modules/ephemeral-storage-additional-support-limitations-for-shared-resource-csi-driver.adoc new file mode 100644 index 000000000000..8c45d98f9bfe --- /dev/null +++ b/modules/ephemeral-storage-additional-support-limitations-for-shared-resource-csi-driver.adoc @@ -0,0 +1,12 @@ +:_content-type: REFERENCE + +[id="ephemeral-storage-additional-support-limitations-for-shared-resource-csi-driver_{context}"] += Additional support limitations for the Shared Resource CSI Driver + +[role="_abstract"] +The Shared Resource CSI Driver has the following noteworthy limitations: + +* The driver is subject to the limitations of Container Storage Interface (CSI) inline ephemeral volumes. +* The value of the `readOnly` field must be `true`. Otherwise, on volume provisioning during pod startup, the driver returns an error to the kubelet. This limitation is in keeping with proposed best practices for the upstream Kubernetes CSI Driver to apply SELinux labels to associated volumes. +* The driver ignores the `FSType` field because it only supports `tmpfs` volumes. +* The driver ignores the `NodePublishSecretRef` field. Instead, it uses `SubjectAccessReviews` with the `use` verb to evaluate whether a pod can obtain a volume that contains `SharedSecret` or `SharedConfigMap` custom resource (CR) instances. diff --git a/modules/ephemeral-storage-csi-inline-overview.adoc b/modules/ephemeral-storage-csi-inline-overview.adoc index 997197e1c7ca..e9c8b73c259f 100644 --- a/modules/ephemeral-storage-csi-inline-overview.adoc +++ b/modules/ephemeral-storage-csi-inline-overview.adoc @@ -15,6 +15,10 @@ This feature allows you to specify CSI volumes directly in the `Pod` specificati By default, {product-title} supports CSI inline ephemeral volumes with these limitations: * Support is only available for CSI drivers. In-tree and FlexVolumes are not supported. -* {product-title} does not include any CSI drivers. Use the CSI drivers provided by -link:https://kubernetes-csi.github.io/docs/drivers.html[community or storage vendors]. Follow the installation instructions provided by the CSI driver. -* CSI drivers might not have implemented the inline volume functionality, including `Ephemeral` capacity. For details, see the CSI driver documentation. +* The Shared Resource CSI Driver supports inline ephemeral volumes as a Technology Preview feature. +* Community or storage vendors provide other CSI drivers that support these volumes. Follow the installation instructions provided by the CSI driver provider. + +CSI drivers might not have implemented the inline volume functionality, including `Ephemeral` capacity. For details, see the CSI driver documentation. + +:FeatureName: Shared Resource CSI Driver +include::snippets/technology-preview.adoc[leveloffset=+0] diff --git a/modules/ephemeral-storage-integration-between-shared-resources-insights-operator-and-openshift-builds.adoc b/modules/ephemeral-storage-integration-between-shared-resources-insights-operator-and-openshift-builds.adoc new file mode 100644 index 000000000000..62691d8cd385 --- /dev/null +++ b/modules/ephemeral-storage-integration-between-shared-resources-insights-operator-and-openshift-builds.adoc @@ -0,0 +1,15 @@ +:_content-type: REFERENCE + +[id="ephemeral-storage-integration-between-shared-resources-insights-operator-and-openshift-builds_{context}"] += Integration between shared resources, Insights Operator, and {product-title} Builds + +[role="_abstract"] +Integration between shared resources, Insights Operator, and {product-title} Builds makes using Red Hat subscriptions (RHEL entitlements) easier in {product-title} Builds. + +Previously, in {product-title} 4.9.x and earlier, you manually imported your credentials and copied them to each project or namespace where you were running builds. + +Now, in {product-title} 4.10 and later, {product-title} Builds can use Red Hat subscriptions (RHEL entitlements) by referencing shared resources and the simple content access feature provided by Insights Operator: + +* The simple content access feature imports your subscription credentials to a well-known `Secret` object. See the links in the following "Additional resources" section. +* The cluster administrator creates a `SharedSecret` custom resource (CR) instance around that `Secret` object and grants permission to particular projects or namespaces. In particular, the cluster administrator gives the `builder` service account permission to use that `SharedSecret` CR instance. +* Builds that run within those projects or namespaces can mount a CSI Volume that references the `SharedSecret` CR instance and its entitled RHEL content. diff --git a/modules/ephemeral-storage-sharing-configmaps-across-namespaces.adoc b/modules/ephemeral-storage-sharing-configmaps-across-namespaces.adoc new file mode 100644 index 000000000000..618f1f65c460 --- /dev/null +++ b/modules/ephemeral-storage-sharing-configmaps-across-namespaces.adoc @@ -0,0 +1,36 @@ +:_content-type: PROCEDURE + +[id="ephemeral-storage-sharing-configmaps-across-namespaces_{context}"] += Sharing a config map across namespaces + +[role="_abstract"] +To share a config map across namespaces in a cluster, you create a `SharedConfigMap` custom resource (CR) instance for that config map. + +.Prerequisites + +You must have permission to perform the following actions: + +* Create instances of the `sharedconfigmaps.sharedresource.openshift.io` custom resource definition (CRD) at a cluster-scoped level. +* Manage roles and role bindings across the namespaces in the cluster to control which users can get, list, and watch those instances. +* Manage roles and role bindings across the namespaces in the cluster to control which service accounts in pods that mount your Container Storage Interface (CSI) volume can use those instances. +* Access the namespaces that contain the Secrets you want to share. + +.Procedure + +. Create a `SharedConfigMap` CR instance for the config map that you want to share across namespaces in the cluster: ++ +[source,terminal] +---- +$ oc apply -f - < + namespace: +EOF +---- + +.Next steps diff --git a/modules/ephemeral-storage-sharing-secrets-across-namespaces.adoc b/modules/ephemeral-storage-sharing-secrets-across-namespaces.adoc new file mode 100644 index 000000000000..fd80147e7c5c --- /dev/null +++ b/modules/ephemeral-storage-sharing-secrets-across-namespaces.adoc @@ -0,0 +1,34 @@ +:_content-type: PROCEDURE + +[id="ephemeral-storage-sharing-secrets-across-namespaces_{context}"] += Sharing secrets across namespaces + +[role="_abstract"] +To share a secret across namespaces in a cluster, you create a `SharedSecret` custom resource (CR) instance for the `Secret` object that you want to share. + +.Prerequisites + +You must have permission to perform the following actions: + +* Create instances of the `sharedsecrets.sharedresource.openshift.io` custom resource definition (CRD) at a cluster-scoped level. +* Manage roles and role bindings across the namespaces in the cluster to control which users can get, list, and watch those instances. +* Manage roles and role bindings to control whether the service account specified by a pod can mount a Container Storage Interface (CSI) volume that references the `SharedSecret` CR instance you want to use. +* Access the namespaces that contain the Secrets you want to share. + +.Procedure + +* Create a `SharedSecret` CR instance for the `Secret` object you want to share across namespaces in the cluster: ++ +[source,terminal] +---- +$ oc apply -f - < + namespace: +EOF +---- diff --git a/modules/ephemeral-storage-using-a-sharedconfigmap-object-in-a-pod.adoc b/modules/ephemeral-storage-using-a-sharedconfigmap-object-in-a-pod.adoc new file mode 100644 index 000000000000..2d06914c3f5c --- /dev/null +++ b/modules/ephemeral-storage-using-a-sharedconfigmap-object-in-a-pod.adoc @@ -0,0 +1,82 @@ +:_content-type: PROCEDURE + +[id="ephemeral-storage-using-a-sharedconfigmap-object-in-a-pod_{context}"] += Using a SharedConfigMap instance in a pod + +[role="_abstract"] +To access a `SharedConfigMap` custom resource (CR) instance from a pod, you grant a given service account RBAC permissions to use that `SharedConfigMap` CR instance. + +.Prerequisites + +* You have created a `SharedConfigMap` CR instance for the config map that you want to share across namespaces in the cluster. +* You must have permission to perform the following actions: +** Create build configs and start builds. +** Discover which `SharedConfigMap` CR instances are available by entering the `oc get sharedconfigmaps` command and getting a non-empty list back. +** Determine if the `builder` service accounts available to you in your namespace are allowed to use the given `SharedSecret` CR instance. That is, you can run `oc adm policy who-can use ` to see if the `builder` service account in your namespace is listed. + +[NOTE] +==== +If neither of the last two prerequisites in this list are met, create, or ask someone to create, the necessary role-based access control (RBAC) so that you can discover `SharedConfigMap` CR instances and enable service accounts to use `SharedConfigMap` CR instances. +==== + +.Procedure + +. Grant a given service account RBAC permissions to use the `SharedConfigMap` CR instance in its pod by using `oc apply` with YAML content. ++ +[NOTE] +==== +Currently, `kubectl` and `oc` have hard-coded special case logic restricting the `use` verb to roles centered around pod security. Therefore, you cannot use `oc create role ...` to create the role needed for consuming a `SharedConfigMap` CR instance. +==== ++ +[source,terminal] +---- +$ oc apply -f - <` to see if the `builder` service account in your namespace is listed. + +[NOTE] +==== +If neither of the last two prerequisites in this list are met, create, or ask someone to create, the necessary role-based access control (RBAC) so that you can discover `SharedSecret` CR instances and enable service accounts to use `SharedSecret` CR instances. +==== + +.Procedure + +. Grant a given service account RBAC permissions to use the `SharedSecret` CR instance in its pod by using `oc apply` with YAML content: ++ +[NOTE] +==== +Currently, `kubectl` and `oc` have hard-coded special case logic restricting the `use` verb to roles centered around pod security. Therefore, you cannot use `oc create role ...` to create the role needed for consuming `SharedSecret` CR instances. +==== ++ +[source,terminal] +---- +$ oc apply -f - <