Persistence and volumes

persistence renders one PersistentVolumeClaim per key and, when you ask for it, mounts the volume into your containers. volumes and volumeMounts cover everything else you need to attach, config maps, secrets, emptyDir, and the rest.

Persistent volume claims

Each key under persistence becomes a PVC named <fullname>-<key>:

persistence:
  data:                 # → PersistentVolumeClaim <fullname>-data

A bare key works: the chart fills in sane defaults. Set fields to override them:

Field	Default	Meaning
size	10Gi	Requested storage.
accessModes	[ReadWriteOnce]	Access modes.
storageClass	cluster default	Storage class to provision from.
keep	true	Adds helm.sh/resource-policy: keep so the PVC survives helm uninstall.

persistence:
  data:
    size: 50Gi
    storageClass: fast-ssd
    keep: true          # default: your data outlives the release

With keep left at its default, the chart writes the retention policy onto the claim as a default annotation:

metadata:
  name: test-data
  annotations:
    helm.sh/resource-policy: keep

Set keep: false when the volume is disposable and should be deleted with the release.

Reusing an existing volume

Set claimName to bind to a PVC that already exists instead of provisioning a new one. It sets the claim's name, and Kubernetes binds to a matching pre-provisioned volume:

persistence:
  data:
    claimName: existing-data-pvc

Mounting a PVC

A PVC is only mounted when the container has configure.persistence: true and the volume declares a mount. The mount path defaults to /<key>:

configure:
  persistence: true     # pod default: mount PVCs into containers

persistence:
  data:
    size: 50Gi
    mount:
      mountPath: /var/lib/app    # defaults to /data if omitted
      subPath: app
      readOnly: false

configure.persistence is off in the chart defaults, so opt in at the pod level (or per container). See Conventions for how configure cascades and how a container opts back out with configure.persistence: false.

Volumes and volume mounts

For volumes that are not PVCs, volumes declares pod volumes and volumeMounts attaches them to containers. Both take a dict form (the key becomes the name) or a native-Kubernetes list form:

# dict mode: key becomes the volume name
volumes:
  config:
    configMap:
      name: my-config

volumeMounts:
  config:
    mountPath: /etc/app
    subPath: config.yaml

# list mode: passed through unchanged
volumes:
  - name: config
    configMap:
      name: my-config

volumes is a pod-level value; volumeMounts cascades from the pod to each container, and a container clears an inherited mount with volumeMounts: {} or []. See Conventions.

Annotations and backups

PVC annotations come from the global annotations value merged with persistence.<key>.annotations. The keep policy above is applied as a chart-generated annotation on top. For backing the volumes up with Velero, see the Velero integration.