From e837f0f80421b808e826231ba307bbde3d156245 Mon Sep 17 00:00:00 2001 From: Takafumi Takahashi Date: Tue, 22 Nov 2022 20:19:54 -0500 Subject: [PATCH] Add document for Cross namespace data sources --- .../concepts/storage/persistent-volumes.md | 68 +++++++++++++++++++ .../feature-gates.md | 6 +- 2 files changed, 73 insertions(+), 1 deletion(-) diff --git a/content/en/docs/concepts/storage/persistent-volumes.md b/content/en/docs/concepts/storage/persistent-volumes.md index 27b2548de6..c719164bc0 100644 --- a/content/en/docs/concepts/storage/persistent-volumes.md +++ b/content/en/docs/concepts/storage/persistent-volumes.md @@ -952,6 +952,25 @@ or to a VolumeSnapshot, the `dataSourceRef` field can contain a reference to any same namespace, except for core objects other than PVCs. For clusters that have the feature gate enabled, use of the `dataSourceRef` is preferred over `dataSource`. +## Cross namespace data sources +{{< feature-state for_k8s_version="v1.26" state="alpha" >}} + +Kubernetes supports cross namespace volume data sources. +To use cross namespace volume data sources, you must enable the `AnyVolumeDataSource` and `CrossNamespaceVolumeDataSource` +[feature gates](/docs/reference/command-line-tools-reference/feature-gates/) for +the kube-apiserver, kube-controller-manager. +Also, you must enable the `CrossNamespaceVolumeDataSource` feature gate for the csi-provisioner. + +Enabling the `CrossNamespaceVolumeDataSource` feature gate allow you to specify a namespace in the dataSourceRef field. +{{< note >}} +When you specify a namespace for a volume data source, Kubernetes checks for a +ReferenceGrant in the other namespace before accepting the reference. +ReferenceGrant is part of the `gateway.networking.k8s.io` extension APIs. +See [ReferenceGrant](https://gateway-api.sigs.k8s.io/api-types/referencegrant/) in the Gateway API documentation for details. +This means that you must extend your Kubernetes cluster with at least ReferenceGrant from the +Gateway API before you can use this mechanism. +{{< /note >}} + ## Data source references The `dataSourceRef` field behaves almost the same as the `dataSource` field. If either one is @@ -969,6 +988,11 @@ users should be aware of: * The `dataSourceRef` field may contain different types of objects, while the `dataSource` field only allows PVCs and VolumeSnapshots. +When the `CrossNamespaceVolumeDataSource` feature is enabled, there are additional differences: + +* The `dataSource` field only allows local objects, while the `dataSourceRef` field allows objects in any namespaces. +* When namespace is specified, `dataSource` and `dataSourceRef` are not synced. + Users should always use `dataSourceRef` on clusters that have the feature gate enabled, and fall back to `dataSource` on clusters that do not. It is not necessary to look at both fields under any circumstance. The duplicated values with slightly different semantics exist only for @@ -1009,6 +1033,50 @@ is registered to handle that kind of data source. When a suitable populator is i responsibility of that populator controller to report Events that relate to volume creation and issues during the process. +### Using a cross-namespace volume data source +{{< feature-state for_k8s_version="v1.26" state="alpha" >}} + +Create a ReferenceGrant to allow the namespace owner to accept the reference. +You define a populated volume by specifying a cross namespace volume data source using the `dataSourceRef` field. You must already have a valid ReferenceGrant in the source namespace: + + ```yaml + apiVersion: gateway.networking.k8s.io/v1beta1 + kind: ReferenceGrant + metadata: + name: allow-ns1-pvc + namespace: default + spec: + from: + - group: "" + kind: PersistentVolumeClaim + namespace: ns1 + to: + - group: snapshot.storage.k8s.io + kind: VolumeSnapshot + name: new-snapshot-demo + ``` + + ```yaml + apiVersion: v1 + kind: PersistentVolumeClaim + metadata: + name: foo-pvc + namespace: ns1 + spec: + storageClassName: example + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + dataSourceRef: + apiGroup: snapshot.storage.k8s.io + kind: VolumeSnapshot + name: new-snapshot-demo + namespace: default + volumeMode: Filesystem + ``` + ## Writing Portable Configuration If you're writing configuration templates or examples that run on a wide range of clusters diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates.md b/content/en/docs/reference/command-line-tools-reference/feature-gates.md index 30d4700157..c940f49834 100644 --- a/content/en/docs/reference/command-line-tools-reference/feature-gates.md +++ b/content/en/docs/reference/command-line-tools-reference/feature-gates.md @@ -72,6 +72,7 @@ For a reference to old feature gates that are removed, please refer to | `CPUManagerPolicyBetaOptions` | `true` | Beta | 1.23 | | | `CPUManagerPolicyOptions` | `false` | Alpha | 1.22 | 1.22 | | `CPUManagerPolicyOptions` | `true` | Beta | 1.23 | | +| `CrossNamespaceVolumeDataSource` | `false` | Alpha| 1.26 | | | `CSIMigrationPortworx` | `false` | Alpha | 1.23 | 1.24 | | `CSIMigrationPortworx` | `false` | Beta | 1.25 | | | `CSIMigrationRBD` | `false` | Alpha | 1.23 | | @@ -410,6 +411,9 @@ Each feature gate is designed for enabling/disabling a specific feature: This feature gate guards *a group* of CPUManager options whose quality level is beta. This feature gate will never graduate to stable. - `CPUManagerPolicyOptions`: Allow fine-tuning of CPUManager policies. +- `CrossNamespaceVolumeDataSource`: Enable the usage of cross namespace volume data source + to allow you to specify a source namespace in the `dataSourceRef` field of a + PersistentVolumeClaim. - `CSIInlineVolume`: Enable CSI Inline volumes support for pods. - `CSIMigration`: Enables shims and translation logic to route volume operations from in-tree plugins to corresponding pre-installed CSI plugins @@ -747,4 +751,4 @@ Each feature gate is designed for enabling/disabling a specific feature: feature, you will also need to enable any associated API resources. For example, to enable a particular resource like `storage.k8s.io/v1beta1/csistoragecapacities`, set `--runtime-config=storage.k8s.io/v1beta1/csistoragecapacities`. - See [API Versioning](/docs/reference/using-api/#api-versioning) for more details on the command line flags. + See [API Versioning](/docs/reference/using-api/#api-versioning) for more details on the command line flags. \ No newline at end of file