Volume Populators and Data Sources [page]deterministic
This document describes _volume populators_ and _data sources_ in Kubernetes. Familiarity with [persistent volumes](/docs/concepts/storage/persistent-volumes/) is suggested.
When you create a [PersistentVolumeClaim](#gloss:persistent-volume-claim), the volume that Kubernetes provisions for it normally starts empty. A _data source_ lets you instead request that the new volume be pre-populated with existing data. _Volume populators_ are the controllers that carry out that population, based on the data source that the PersistentVolumeClaim references.
Kubernetes has built-in support for data sources that [clone an existing volume](/docs/concepts/storage/volume-pvc-datasource/) or that [restore a volume snapshot](/docs/concepts/storage/volume-snapshots/). Custom volume populators extend this mechanism. The data source is a custom resource, that is, an object whose type is defined by a [CustomResourceDefinition](#gloss:CustomResourceDefinition). A populator controller watches for PersistentVolumeClaims that reference such a resource and fills the new volume from it.
## Volume populators and data sources
Kubernetes supports custom volume populators. To use custom volume populators, you must enable the `AnyVolumeDataSource` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) for the kube-apiserver and kube-controller-manager.
Volume populators take advantage of a PVC spec field called `dataSourceRef`. Unlike the `dataSource` field, which can only contain either a reference to another PersistentVolumeClaim or to a VolumeSnapshot, the `dataSourceRef` field can contain a reference to any object in the 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`.
## Data source references
The `dataSourceRef` field behaves almost the same as the `dataSource` field. If one is specified while the other is not, the API server will give both fields the same value. Neither field can be changed after creation, and attempting to specify different values for the two fields will result in a validation error. Therefore the two fields will always have the same contents.
There are two differences between the `dataSourceRef` field and the `dataSource` field that users should be aware of:
* The `dataSource` field ignores invalid values (as if the field was blank) while the `dataSourceRef` field never ignores values and will cause an error if an invalid value is used. Invalid values are any core object (objects with no apiGroup) except for PVCs. * 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 backwards compatibility. In particular, a mixture of older and newer controllers are able to interoperate because the fields are the same.
### Using volume populators
Volume populators are [controllers](#gloss:controller) that can create non-empty volumes, where the contents of the volume are determined by a Custom Resource. Users create a populated volume by referring to a Custom Resource using the `dataSourceRef` field:
```yaml apiVersion: v1 kind: PersistentVolumeClaim metadata: name: populated-pvc spec: dataSourceRef: name: example-name kind: ExampleDataSource apiGroup: example.storage.k8s.io accessModes: - ReadWriteOnce resources: …(trimmed)