persistence

Configure persistent storage and mount options. Each key is an identifier for a persistence item. Supported types: persistentVolumeClaim (default), configMap, secret, nfs, emptyDir, hostPath, image, projected, custom. By default each item mounts to /<identifier>. Use globalMounts or advancedMounts to customize mount paths.

Type

object

Usage

Keys are identifiers for persistence instances.

persistence:
  main:
    enabled: true
    # ... configuration

  secondary:
    enabled: true
    # ... configuration

Examples

persistence:
  config:
    type: persistentVolumeClaim
    accessMode: ReadWriteOnce
    size: 1Gi
    globalMounts:
      - path: /config
  tmp:
    type: emptyDir

persistence:
  api-token:
    type: projected
    defaultMode: 0400
    sources:
      - serviceAccountToken:
          audience: https://api.example.com
          expirationSeconds: 3600
          path: token
    globalMounts:
      - path: /var/run/secrets/tokens

More examples (22)

persistence:
  config:
    type: persistentVolumeClaim
    accessMode: ReadWriteOnce
    size: 1Gi

persistence:
  config:
    type: persistentVolumeClaim
    accessMode: ReadWriteOnce
    size: 10Gi
    storageClass: fast-ssd
    retain: true
    globalMounts:
      - path: /config

persistence:
  config:
    type: persistentVolumeClaim
    existingClaim: my-app-data

persistence:
  config:
    type: configMap
    name: my-configmap

persistence:
  config:
    type: configMap
    identifier: my-chart-configmap
    globalMounts:
      - path: /etc/app/config
        readOnly: true

persistence:
  config:
    type: configMap
    name: my-configmap
    items:
      - key: settings.yaml
        path: settings.yaml

persistence:
  credentials:
    type: secret
    name: my-secret

persistence:
  tls:
    type: secret
    name: app-tls-cert
    globalMounts:
      - path: /etc/ssl/certs
        readOnly: true

persistence:
  media:
    type: nfs
    server: 192.168.1.100
    path: /mnt/share/media

persistence:
  backups:
    type: nfs
    server: nas.example.lan
    path: /volume/Backups/k8s/app
    globalMounts:
      - path: /backups

persistence:
  tmp:
    type: emptyDir

persistence:
  cache:
    type: emptyDir
    medium: Memory
    sizeLimit: 256Mi

persistence:
  cache:
    type: ephemeral

persistence:
  cache:
    type: ephemeral
    accessMode: ReadWriteOnce
    storageClass: fast-ssd
    size: 10Gi

persistence:
  dev-tun:
    type: hostPath
    hostPath: /dev/net/tun
    hostPathType: CharDevice

persistence:
  data:
    type: hostPath
    hostPath: /mnt/local-data
    hostPathType: DirectoryOrCreate

persistence:
  static-assets:
    type: image
    image: registry.example.com/assets:v1.0

persistence:
  tools:
    type: image
    image:
      repository: registry.example.com/tools
      tag: latest
    pullPolicy: Always

persistence:
  api-token:
    type: projected
    sources:
      - serviceAccountToken:
          audience: https://api.example.com
          expirationSeconds: 3600
          path: token

persistence:
  bundle:
    type: projected
    defaultMode: 0400
    sources:
      - serviceAccountToken:
          audience: vault
          path: vault-token
      - configMap:
          name: ca-bundle
          items:
            - key: ca.crt
              path: ca.crt

persistence:
  ceph:
    type: custom
    volumeSpec:
      cephfs:
        monitors:
          - 10.0.0.1:6789
        user: admin
        secretRef:
          name: ceph-secret

persistence:
  projected:
    type: custom
    volumeSpec:
      projected:
        sources:
          - secret:
              name: my-secret
          - configMap:
              name: my-config

Type Variants

persistentVolumeClaim (1)

Dynamically provision a PersistentVolumeClaim. This is the default persistence type and will be used when no type is specified.

persistence:
  config:
    type: persistentVolumeClaim
    accessMode: ReadWriteOnce
    size: 1Gi

Property	Type	Required	Default	Description
accessMode	string	Yes	-	AccessMode for the persistent volume. Make sure to select…
annotations	object / null	No	-	Annotations to set on the item. Keys and values support H…
dataSource	object	No	-	The optional data source for the persistentVolumeClaim. S…
dataSourceRef	object	No	-	The optional volume populator for the persistentVolumeCla…
forceRename	string	No	-	Override the default resource name. Mutually exclusive wi…
labels	object / null	No	-	Labels to set on the item. Keys and values support Helm t…
prefix	string	No	“	Prefix to prepend to the resource name. Mutually exclusiv…
retain	boolean	No	-	Set to true to retain the PVC upon helm uninstall.
size	string	Yes	-	The amount of storage that is requested for the persisten…
storageClass	string	No	-	Storage Class for the config volume. If set to ’-&#39…
suffix	string	No	-	Suffix to append to the resource name. Defaults to the re…
volumeName	string	No	-

Property details

accessMode

AccessMode for the persistent volume. Make sure to select an access mode that is supported by your storage provider! See https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes

annotations

Annotations to set on the item. Keys and values support Helm templating.

dataSource

The optional data source for the persistentVolumeClaim. See https://kubernetes.io/docs/concepts/storage/persistent-volumes/#volume-populators-and-data-sources

dataSourceRef

The optional volume populator for the persistentVolumeClaim. See https://kubernetes.io/docs/concepts/storage/persistent-volumes/#volume-populators-and-data-sources

forceRename

Override the default resource name. Mutually exclusive with prefix and suffix.

labels

Labels to set on the item. Keys and values support Helm templating.

prefix

Prefix to prepend to the resource name. Mutually exclusive with forceRename.

size

The amount of storage that is requested for the persistent volume.

storageClass

Storage Class for the config volume. If set to ’-’, dynamic provisioning is disabled. If set to something else, the given storageClass is used. If undefined (the default) or set to null, no storageClassName spec is set, choosing the default provisioner.

suffix

Suffix to append to the resource name. Defaults to the resource identifier if there are multiple items, otherwise empty. Mutually exclusive with forceRename.

persistentVolumeClaim (2)

Attach an existing PersistentVolumeClaim instead of creating a new one.

persistence:
  config:
    type: persistentVolumeClaim
    existingClaim: my-app-data

Property	Type	Required	Default	Description
existingClaim	string	Yes	-	The name of an existing PersistentVolumeClaim to use. Thi…

Property details

existingClaim

The name of an existing PersistentVolumeClaim to use. This will not create a new PVC, but use the existing one instead.

configMap

Mount a ConfigMap as a volume. Use ‘name’ for external ConfigMaps, or ‘identifier’ to reference one managed by this chart.

persistence:
  config:
    type: configMap
    name: my-configmap

Property	Type	Required	Default	Description
defaultMode	integer	No	-
identifier	string	No	-
items	array	No	-
name	string	Yes	-

secret

Mount a Secret as a volume. Use ‘name’ for an existing Secret, ‘identifier’ for a Secret managed by this chart, or ‘externalSecretRef’ for an ExternalSecret managed by this chart.

persistence:
  credentials:
    type: secret
    name: my-secret

Property	Type	Required	Default	Description
defaultMode	integer	No	-
externalSecretRef	string	No	-
identifier	string	No	-
items	array	No	-
name	string	Yes	-

nfs

Mount an NFS share as a volume.

persistence:
  media:
    type: nfs
    server: 192.168.1.100
    path: /mnt/share/media

Property	Type	Required	Default	Description
path	string	Yes	-	The NFS export path on the server.
server	string	Yes	-	The NFS server hostname or IP address.

emptyDir

Use an emptyDir volume for scratch space or sharing data between containers in the same pod. Data is lost when the pod is removed.

persistence:
  tmp:
    type: emptyDir

Property	Type	Required	Default	Description
medium	string	No	-	Storage medium. Set to ‘Memory’ for tmpfs (RAM-ba…
sizeLimit	string	No	-	Maximum size of the volume (e.g. ‘1Gi’). Only enf…

Property details

medium

Storage medium. Set to ‘Memory’ for tmpfs (RAM-backed). Leave empty for node disk.

sizeLimit

Maximum size of the volume (e.g. ‘1Gi’). Only enforced for tmpfs.

ephemeral

Use a generic ephemeral volume for scratch space or sharing data between containers. The volume is created and deleted with the pod.

persistence:
  cache:
    type: ephemeral

Property	Type	Required	Default	Description
accessMode	string	No	-	AccessMode for the ephemeral volume. Make sure to select …
size	string	No	-	The amount of storage that is requested for the ephemeral…
storageClass	string	No	-	Storage Class for the ephemeral volume. If set to ’-&…

Property details

accessMode

AccessMode for the ephemeral volume. Make sure to select an access mode that is supported by your storage provider! See https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes

size

The amount of storage that is requested for the ephemeral volume.

storageClass

Storage Class for the ephemeral volume. If set to ’-’, dynamic provisioning is disabled. If set to something else, the given storageClass is used. If undefined (the default) or set to null, no storageClassName spec is set, choosing the default provisioner.

hostPath

Mount a path from the host node into the pod. Use with caution as it ties the pod to a specific node.

persistence:
  dev-tun:
    type: hostPath
    hostPath: /dev/net/tun
    hostPathType: CharDevice

Property	Type	Required	Default	Description
hostPath	string	No	-	Path on the host node to mount.
hostPathType	string	No	-	Type of the host path. Values: DirectoryOrCreate, Directo…

Property details

hostPathType

Type of the host path. Values: DirectoryOrCreate, Directory, FileOrCreate, File, Socket, CharDevice, BlockDevice.

image

Mount OCI image or artifact contents as a read-only volume. Requires Kubernetes 1.31+ with the ImageVolume feature gate.

persistence:
  static-assets:
    type: image
    image: registry.example.com/assets:v1.0

Property	Type	Required	Default	Description
image	object	Yes	-	OCI artifact reference to be used.
pullPolicy	string	No	-	The image pull policy for the image persistence item.

projected

Project one or more sources into a single volume. Sources may be ServiceAccount tokens, ConfigMaps or Secrets, all mounted into the same directory.

persistence:
  api-token:
    type: projected
    sources:
      - serviceAccountToken:
          audience: https://api.example.com
          expirationSeconds: 3600
          path: token

Property	Type	Required	Default	Description
defaultMode	integer	No	-	Permissions applied to the projected files, in octal (for…
sources	array	Yes	-	The list of volume projections to mount into this volume.

Property details

defaultMode

Permissions applied to the projected files, in octal (for example 0400). Individual items may override this.

custom

Specify a custom volume type not covered by the built-in types. The volumeSpec is passed through directly to the pod spec.

persistence:
  ceph:
    type: custom
    volumeSpec:
      cephfs:
        monitors:
          - 10.0.0.1:6789
        user: admin
        secretRef:
          name: ceph-secret

Property	Type	Required	Default	Description
volumeSpec	object	Yes	-	Raw Kubernetes volume specification. Passed through direc…

Property details

volumeSpec

Raw Kubernetes volume specification. Passed through directly to the pod spec volumes list.

Instance Properties

Common properties:

Property	Type	Required	Default	Description
accessMode	string	Yes	-	AccessMode for the persistent volume. Make sure to select…
advancedMounts	object	No	-	Explicitly configure mounts for specific controllers and …
annotations	object / null	No	-	Annotations to set on the item. Keys and values support H…
dataSource	object	No	-	The optional data source for the persistentVolumeClaim. S…
dataSourceRef	object	No	-	The optional volume populator for the persistentVolumeCla…
enabled	boolean	No	true	Set to false to disable the persistence item.
forceRename	string	No	-	Override the default resource name. Mutually exclusive wi…
globalMounts	array	No	-	Configure mounts to all controllers and containers. By de…
labels	object / null	No	-	Labels to set on the item. Keys and values support Helm t…
prefix	string	No	“	Prefix to prepend to the resource name. Mutually exclusiv…
retain	boolean	No	-	Set to true to retain the PVC upon helm uninstall.
size	string	Yes	-	The amount of storage that is requested for the persisten…
storageClass	string	No	-	Storage Class for the config volume. If set to ’-&#39…
suffix	string	No	-	Suffix to append to the resource name. Defaults to the re…
type	any	No	-
volumeName	string	No	-

Property Details

accessMode

AccessMode for the persistent volume. Make sure to select an access mode that is supported by your storage provider! See https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes

advancedMounts

Explicitly configure mounts for specific controllers and containers. Structure: advancedMounts.<controller_name>.<container_name>[].path Use this instead of globalMounts when different controllers need different mount configurations.

annotations

Annotations to set on the item. Keys and values support Helm templating.

forceRename

Override the default resource name. Mutually exclusive with prefix and suffix.

globalMounts

Configure mounts to all controllers and containers. By default the persistence item will be mounted to /<name_of_the_persistence_item>. Each entry supports: path, readOnly, subPath, subPathExpr, and mountPropagation.

labels

Labels to set on the item. Keys and values support Helm templating.

prefix

Prefix to prepend to the resource name. Mutually exclusive with forceRename.

size

The amount of storage that is requested for the persistent volume.

storageClass

Storage Class for the config volume. If set to ’-’, dynamic provisioning is disabled. If set to something else, the given storageClass is used. If undefined (the default) or set to null, no storageClassName spec is set, choosing the default provisioner.

suffix

Suffix to append to the resource name. Defaults to the resource identifier if there are multiple items, otherwise empty. Mutually exclusive with forceRename.

Related Pages

• dataSource
• dataSourceRef