Merge pull request #28869 from verult/fsgroup-to-csi

Documentation for delegating FSGroup change to CSI driver

content/en/docs/reference/command-line-tools-reference/feature-gates.md

@@ -96,6 +96,7 @@ different Kubernetes components.
 | `DaemonSetUpdateSurge` | `true` | Beta | 1.22 | |
 | `DefaultPodTopologySpread` | `false` | Alpha | 1.19 | 1.19 |
 | `DefaultPodTopologySpread` | `true` | Beta | 1.20 | |
+| `DelegateFSGroupToCSIDriver` | `false` | Alpha | 1.22 | |
 | `DevicePlugins` | `false` | Alpha | 1.8 | 1.9 |
 | `DevicePlugins` | `true` | Beta | 1.10 | |
 | `DisableAcceleratorUsageMetrics` | `false` | Alpha | 1.19 | 1.19 |
@@ -647,6 +648,9 @@ Each feature gate is designed for enabling/disabling a specific feature:
   availability during update per node.
 - `DefaultPodTopologySpread`: Enables the use of `PodTopologySpread` scheduling plugin to do
   [default spreading](/docs/concepts/workloads/pods/pod-topology-spread-constraints/#internal-default-constraints).
+- `DelegateFSGroupToCSIDriver`: If supported by the CSI driver, delegates the
+  role of applying `fsGroup` from a Pod's `securityContext` to the driver by
+  passing `fsGroup` through the NodeStageVolume and NodePublishVolume CSI calls.
 - `DevicePlugins`: Enable the [device-plugins](/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins/)
   based resource provisioning on nodes.
 - `DisableAcceleratorUsageMetrics`:

content/en/docs/tasks/configure-pod-container/security-context.md

@@ -184,6 +184,25 @@ This field has no effect on ephemeral volume types such as
 and [`emptydir`](/docs/concepts/storage/volumes/#emptydir).
 {{< /note >}}
 
+## Delegating volume permission and ownership change to CSI driver
+
+{{< feature-state for_k8s_version="v1.22" state="alpha" >}}
+
+If you deploy a [Container Storage Interface (CSI)](https://github.com/container-storage-interface/spec/blob/master/spec.md)
+driver which supports the `VOLUME_MOUNT_GROUP` `NodeServiceCapability`, the
+process of setting file ownership and permissions based on the
+`fsGroup` specified in the `securityContext` will be performed by the CSI driver
+instead of Kubernetes, provided that the `DelegateFSGroupToCSIDriver` Kubernetes
+feature gate is enabled. In this case, since Kubernetes doesn't perform any
+ownership and permission change, `fsGroupChangePolicy` does not take effect, and
+as specified by CSI, the driver is expected to mount the volume with the
+provided `fsGroup`, resulting in a volume that is readable/writable by the
+`fsGroup`.
+
+Please refer to the [KEP](https://github.com/gnufied/enhancements/blob/master/keps/sig-storage/2317-fsgroup-on-mount/README.md)
+and the description of the `VolumeCapability.MountVolume.volume_mount_group`
+field in the [CSI spec](https://github.com/container-storage-interface/spec/blob/master/spec.md#createvolume)
+for more information.
 
 ## Set the security context for a Container