[enterprise-4.10] RHDEVDOCS-3279 Integrate Shared Resources Operator with Cluster Storage

_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

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[]

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.

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.

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]

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.

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 - <<EOF
+apiVersion: sharedresource.openshift.io/v1alpha1
+kind: SharedConfigMap
+metadata:
+  name: my-share
+spec:
+  secretRef:
+    name: <name of configmap>
+    namespace: <namespace of configmap>
+EOF
+----
+
+.Next steps

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 - <<EOF
+apiVersion: sharedresource.openshift.io/v1alpha1
+kind: SharedSecret
+metadata:
+  name: my-share
+spec:
+  secretRef:
+    name: <name of secret>
+    namespace: <namespace of secret>
+EOF
+----

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 <identifier of specific SharedSecret>` 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 - <<EOF
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: shared-resource-my-share
+  namespace: my-namespace
+rules:
+  - apiGroups:
+      - sharedresource.openshift.io
+    resources:
+      - sharedconfigmaps
+    resourceNames:
+      - my-share
+    verbs:
+      - use
+EOF
+----
+
+. Create the `RoleBinding` associated with the role by using the `oc` command:
++
+[source,terminal]
+----
+oc create rolebinding shared-resource-my-share --role=shared-resource-my-share --serviceaccount=my-namespace:builder
+----
+
+. Access the `SharedConfigMap` CR instance from a pod:
++
+[source,terminal]
+----
+$ oc apply -f - <<EOF
+kind: Pod
+apiVersion: v1
+metadata:
+  name: my-app
+  namespace: my-namespace
+spec:
+  serviceAccountName: default
+
+# containers omitted …. Follow standard use of ‘volumeMounts’ for referencing your shared resource volume
+
+    volumes:
+    - name: my-csi-volume
+      csi:
+        readOnly: true
+        driver: csi.sharedresource.openshift.io
+        volumeAttributes:
+          sharedConfigMap: my-share
+
+EOF
+----

modules/ephemeral-storage-using-a-sharedsecrets-resource-in-a-pod.adoc

@@ -0,0 +1,82 @@
+:_content-type: PROCEDURE
+
+[id="ephemeral-storage-using-a-sharedsecrets-resource-in-a-pod_{context}"]
+= Using a SharedSecret instance in a pod
+
+[role="_abstract"]
+To access a `SharedSecret` custom resource (CR) instance from a pod, you grant a given service account RBAC permissions to use that `SharedSecret` CR instance.
+
+.Prerequisites
+
+* You have created a `SharedSecret` CR instance for the secret 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 `SharedSecret` CR instances are available by entering the `oc get sharedsecrets` 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 <identifier of specific SharedSecret>` 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 - <<EOF
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: shared-resource-my-share
+  namespace: my-namespace
+rules:
+  - apiGroups:
+      - sharedresource.openshift.io
+    resources:
+      - sharedsecrets
+    resourceNames:
+      - my-share
+    verbs:
+      - use
+EOF
+----
+
+. Create the `RoleBinding` associated with the role by using the `oc` command:
++
+[source,terminal]
+----
+$ oc create rolebinding shared-resource-my-share --role=shared-resource-my-share --serviceaccount=my-namespace:builder
+----
+
+. Access the `SharedSecret` CR instance from a pod:
++
+[source,terminal]
+----
+$ oc apply -f - <<EOF
+kind: Pod
+apiVersion: v1
+metadata:
+  name: my-app
+  namespace: my-namespace
+spec:
+  serviceAccountName: default
+
+# containers omitted …. Follow standard use of ‘volumeMounts’ for referencing your shared resource volume
+
+    volumes:
+    - name: my-csi-volume
+      csi:
+        readOnly: true
+        driver: csi.sharedresource.openshift.io
+        volumeAttributes:
+          sharedSecret: my-share
+
+EOF
+----

modules/persistent-storage-csi-cloning-overview.adoc

@@ -22,7 +22,7 @@ By default, {product-title} supports CSI volume cloning with these limitations:
 * The source and destination storage class must be the same.
 * 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.
+link:https://kubernetes-csi.github.io/docs/drivers.html[community or storage vendors]. Follow the installation instructions furnished by the CSI driver provider.
 * CSI drivers might not have implemented the volume cloning functionality. For details, see the CSI driver documentation.
 * {product-title} {product-version} supports version 1.1.0 of the
 link:https://github.com/container-storage-interface/spec[CSI specification].

modules/persistent-storage-csi-snapshots-overview.adoc

@@ -8,7 +8,7 @@
 
 A _snapshot_ represents the state of the storage volume in a cluster at a particular point in time. Volume snapshots can be used to provision a new volume.
 
-{product-title} supports CSI volume snapshots by default. However, a specific CSI driver is required.
+{product-title} supports Container Storage Interface (CSI) volume snapshots by default. However, a specific CSI driver is required.
 
 With CSI volume snapshots, a cluster administrator can:
 
@@ -28,5 +28,5 @@ Be aware of the following when using volume snapshots:
 
 * Support is only available for CSI drivers. In-tree and FlexVolumes are not supported.
 * {product-title} only ships with select CSI drivers. For CSI drivers that are not provided by an {product-title} Driver Operator, it is recommended to 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.
+link:https://kubernetes-csi.github.io/docs/drivers.html[community or storage vendors]. Follow the installation instructions furnished by the CSI driver provider.
 * CSI drivers may or may not have implemented the volume snapshot functionality. CSI drivers that have provided support for volume snapshots will likely use the `csi-external-snapshotter` sidecar. See documentation provided by the CSI driver for details.