A volume claim template describes the storage a Pod needs without requiring you to create its PersistentVolumeClaim (PVC) by hand. Kubernetes creates a claim from the template. Where you put the template determines whether that claim belongs to one short-lived Pod or to a particular StatefulSet replica. section 10.5.1 section 16.1.2
Use the template in one of two places:
- For an ephemeral volume, put `volumeClaimTemplate` under a volume in the Pod manifest. Its `spec` has the fields of a PVC manifest. The resulting claim is exclusive to the Pod, and its lifecycle is tied to that Pod. section 10.5.1
- For a StatefulSet, put named templates in `spec.volumeClaimTemplates`. The controller creates a separate claim for each replica. The template name must match the volume name in the Pod template. section 16.1.2 section 16.1.3
A claim created with an ephemeral volume
A Pod volume named `my-volume` requests `ReadWriteOnce` access and `1Gi` of storage through `volumeClaimTemplate`. With no `storageClassName` specified, it uses the cluster’s default StorageClass. Creating the Pod produces a claim named `demo-ephemeral-my-volume`—the Pod name followed by the volume name. Check it with `kubectl get pvc demo-ephemeral-my-volume`; the example claim is bound to a PersistentVolume. section 10.5.1
Listing 10.15 Defining an ephemeral volume in a pod manifest
apiVersion: v1
kind: Pod
metadata:
name: demo-ephemeral
spec:
volumes:
- name: my-volume #1
ephemeral: #1
volumeClaimTemplate: #2
spec: #2
accessModes: #2
- ReadWriteOnce #2
resources: #2
requests: #2
storage: 1Gi #2
containers: #2
- name: main
image: busybox
command:
- sh
- -c
- |
echo "This is a demo of a Pod using an ephemeral volume." ;
touch /mnt/ephemeral/file-created-by-$HOSTNAME.txt ;
sleep infinity
volumeMounts:
- mountPath: /mnt/ephemeral
name: my-volume
terminationGracePeriodSeconds: 0
The Pod manifest shows the template inside an ephemeral volume and the container mounting that volume at `/mnt/ephemeral`. section 10.5.1
StatefulSet claims serve a different lifecycle. Each replica gets its own claim, identified by the template name and the replica’s ordinal: `db-data-quiz-0`, `db-data-quiz-1`, and `db-data-quiz-2` are three distinct claims. If a StatefulSet Pod is deleted and recreated, its ordinal—and its association with the corresponding claim—stays the same. That lets the replacement use the same state rather than a new replica’s storage. section 16.1.2 section 16.1.4
$ kubectl get pvc -l app=quiz NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE db-data-quiz-0 Bound pvc...1bf8ccaf 1Gi RWO standard 10m db-data-quiz-1 Bound pvc...c8f860c2 1Gi RWO standard 10m db-data-quiz-2 Bound pvc...2cc494d6 1Gi RWO standard 10m
The `kubectl get pvc` output shows one bound claim for each of three StatefulSet replicas. section 16.1.4
To check what the controller created, use `kubectl describe sts quiz` to see the claim template and creation events, then `kubectl get pvc` to see the individual claims. An ephemeral Pod’s claim is tied to that Pod; a StatefulSet template instead gives each replica a consistent claim association when its Pod is recreated. section 10.5.1 section 16.1.4
