Skip to content
Français
Account: not signed in, sync available My learning
Select theme
Français

Kubernetes application volumes: share and inject your data

By updated

Improve this page

Logo Kubernetes

A container only sees the filesystem of its image, and what it writes there disappears when it restarts. A volume is a folder declared in the Pod, which several containers can mount to share files or to receive data from Kubernetes: configuration, secrets, Pod metadata. In this lesson, you prove what an emptyDir volume shares and what it keeps isolated, you see what survives a restart, you mount several sources into a single folder, then you fix a read refusal with fsGroup.

You need the lesson Pods and the demo cluster created in First cluster. ConfigMaps and Secrets are recalled here in a few lines; their creation and full usage are covered in ConfigMaps and Secrets.

What you will learn

  • Declare an emptyDir volume and mount it in two containers, one of them read-only
  • Prove what is shared, what stays isolated and what survives a restart
  • Mount an emptyDir in memory with a bounded size
  • Gather ConfigMap, Secret and Pod metadata in a projected volume
  • Diagnose a read refusal and fix it with fsGroup
  • Recognize the danger of a hostPath volume
  • Choose the volume type that fits a need with the decision table

What is a Kubernetes volume?

A volume is declared in two steps: in the Pod's spec.volumes (its name and its type), then in the volumeMounts of each container that uses it (the name and the mount path). The volumes of this lesson are application volumes: they exist to exchange or inject data, and they are not persistent storage. For data that must outlive the Pod, see Storage.

You work in a dedicated namespace, deleted at the end:

Terminal window
kubectl config use-context kind-demo && kubectl create namespace volumes
Switched to context "kind-demo".
namespace/volumes created

The names and messages of this lesson are in French on purpose, so that the outputs stay those of the tested cluster: partage means "share", producteur "producer", lecteur "reader", echange "exchange", arret "stop", prive "private", ecriture "write", reglages "settings", acces "access", cle "key", identite "identity", projete "projected", pod-nom "pod name", limite-memoire "memory limit", etape "step", droits "rights", noeud "node", hote "host", memoire "memory", rapide "fast", valeur-demo "demo value" and "propre au conteneur" "specific to the container".

emptyDir: temporary sharing between containers

An emptyDir is an empty folder, created when the Pod starts on a node and deleted with it. The partage Pod has two containers. The producteur appends a timestamped line every two seconds to the echange volume, generates an identifier only once, and also writes a file in its own /tmp. The lecteur mounts the same volume read-only. The /echange/arret file will let you make the producer exit with an error on demand, to observe a restart.

Terminal window
mkdir -p ~/atelier-k8s/volumes && cd ~/atelier-k8s/volumes
cat > partage.yaml <<'EOF'
apiVersion: v1
kind: Pod
metadata:
name: partage
spec:
containers:
- name: producteur
image: busybox:1.38.0@sha256:a46257e06c82ad85242d0d38077d0a52d9896389ca60a1a59d3463db586e5fa4
command:
- sh
- -c
- |
[ -f /echange/id.txt ] || cat /proc/sys/kernel/random/uuid > /echange/id.txt
echo "propre au conteneur" > /tmp/prive.txt
rm -f /echange/arret
while [ ! -f /echange/arret ]; do
date +%T >> /echange/lignes.txt
sleep 2
done
exit 1
volumeMounts:
- name: echange
mountPath: /echange
- name: lecteur
image: busybox:1.38.0@sha256:a46257e06c82ad85242d0d38077d0a52d9896389ca60a1a59d3463db586e5fa4
command: ["sh", "-c", "sleep 3600"]
volumeMounts:
- name: echange
mountPath: /echange
readOnly: true
volumes:
- name: echange
emptyDir: {}
EOF
kubectl apply -f partage.yaml -n volumes && kubectl wait --for=condition=Ready pod/partage -n volumes --timeout=90s && sleep 6 && kubectl exec partage -n volumes -c lecteur -- cat /echange/lignes.txt
pod/partage created
pod/partage condition met
15:05:03
15:05:05
15:05:07
15:05:09

The reader reads what the producer writes: the volume is shared. Now check that the rest of the filesystem is not. The producer wrote /tmp/prive.txt outside the volume:

Terminal window
kubectl exec partage -n volumes -c lecteur -- ls /tmp/prive.txt
ls: /tmp/prive.txt: No such file or directory
command terminated with exit code 1

The reader does not see this file. It does exist, but only in the producer's filesystem:

Terminal window
kubectl exec partage -n volumes -c producteur -- cat /tmp/prive.txt
propre au conteneur

A volume therefore only shares its own folder: anything a container writes elsewhere stays invisible to the others. The reader's read-only mount can be checked too:

Terminal window
kubectl exec partage -n volumes -c lecteur -- sh -c 'echo test > /echange/ecriture.txt'
sh: line 0: can't create /echange/ecriture.txt: Read-only file system
command terminated with exit code 1

The line 0: prefix comes from busybox 1.38.0, the image of the demonstration; another version of the shell may write sh: can't create … without it. The volume is the same, but readOnly: true is a setting of the mount, specific to each container: the reader cannot write while the producer can.

What survives a restart, and what disappears with the Pod

First note the identifier generated by the producer:

Terminal window
kubectl exec partage -n volumes -c lecteur -- cat /echange/id.txt > /tmp/id-avant.txt; cat /tmp/id-avant.txt
51b4b2e2-304f-4e58-b8f9-dd44ae6e68b8

Then make the producer exit with an error by creating the arret file from it. The first command, from the reader, is refused because of the read-only mount:

Terminal window
kubectl exec partage -n volumes -c lecteur -- touch /echange/arret 2>&1 | head -n 2; kubectl exec partage -n volumes -c producteur -- touch /echange/arret && sleep 8 && kubectl get pod partage -n volumes
touch: /echange/arret: Read-only file system
command terminated with exit code 1
NAME READY STATUS RESTARTS AGE
partage 2/2 Running 1 (7s ago) 15s

The RESTARTS column shows 1: only the producteur container restarted, the Pod is the same. Read the volume and the producer's /tmp again:

Terminal window
kubectl exec partage -n volumes -c lecteur -- sh -c 'cat /echange/id.txt; wc -l < /echange/lignes.txt'; kubectl exec partage -n volumes -c producteur -- ls /tmp/prive.txt
51b4b2e2-304f-4e58-b8f9-dd44ae6e68b8
8
/tmp/prive.txt

The identifier is unchanged and the lines file kept its 8 lines: the volume survives the restart of a container. /tmp/prive.txt is there because the producer recreated it when it started again; a file placed by hand in /tmp before the restart would have disappeared, because the filesystem of a restarted container starts again from its image.

Finally, delete the whole Pod and recreate it:

Terminal window
kubectl delete pod partage -n volumes && kubectl apply -f partage.yaml -n volumes && kubectl wait --for=condition=Ready pod/partage -n volumes --timeout=90s && sleep 4 && kubectl exec partage -n volumes -c lecteur -- cat /echange/id.txt
pod "partage" deleted from volumes namespace
pod/partage created
pod/partage condition met
867eae69-d020-4ab5-b9ff-563be6634a48

The identifier is new, compared to 51b4b2e2: the emptyDir is tied to the Pod and disappears with it. What you have just measured sums up as follows:

What is written in…Container restartPod deletion
The emptyDir volumeKeptLost
The container's filesystem (/tmp)LostLost

The volume survives a container restart, not the deletion of the Pod.

emptyDir in memory (RAM)

With medium: Memory, the emptyDir becomes a tmpfs, a filesystem that lives in RAM: it is faster than a disk. It counts toward the container's memory: bound its size with sizeLimit.

Terminal window
cat > memoire.yaml <<'EOF'
apiVersion: v1
kind: Pod
metadata:
name: rapide
spec:
containers:
- name: app
image: busybox:1.38.0@sha256:a46257e06c82ad85242d0d38077d0a52d9896389ca60a1a59d3463db586e5fa4
command: ["sh", "-c", "sleep 3600"]
volumeMounts:
- name: cache
mountPath: /cache
volumes:
- name: cache
emptyDir:
medium: Memory
sizeLimit: 16Mi
EOF
kubectl apply -f memoire.yaml -n volumes && kubectl wait --for=condition=Ready pod/rapide -n volumes --timeout=90s && kubectl exec rapide -n volumes -- df -h /cache
pod/rapide created
pod/rapide condition met
Filesystem Size Used Available Use% Mounted on
tmpfs 16.0M 0 16.0M 0% /cache

The folder is a 16 MB tmpfs, the size requested. This form suits a throwaway cache; for a volume that must last or grow, use storage.

projected: combine several sources

A projected volume gathers several sources into a single folder: ConfigMap, Secret and downwardAPI, which exposes Pod metadata (name, labels, resource limits) as files. First create a ConfigMap and a Secret:

Terminal window
kubectl create configmap reglages -n volumes --from-literal=MODE=demo && kubectl create secret generic acces -n volumes --from-literal=cle=valeur-demo
configmap/reglages created
secret/acces created

The identite Pod projects into /etc/projete the ConfigMap key, the Secret key, its own name, its labels and its memory limit:

Terminal window
cat > identite.yaml <<'EOF'
apiVersion: v1
kind: Pod
metadata:
name: identite
labels:
app: identite
etape: "1"
spec:
containers:
- name: app
image: busybox:1.38.0@sha256:a46257e06c82ad85242d0d38077d0a52d9896389ca60a1a59d3463db586e5fa4
command: ["sh", "-c", "sleep 3600"]
resources:
limits:
cpu: 500m
memory: 64Mi
volumeMounts:
- name: projete
mountPath: /etc/projete
readOnly: true
volumes:
- name: projete
projected:
sources:
- configMap:
name: reglages
items:
- key: MODE
path: mode.txt
- secret:
name: acces
items:
- key: cle
path: secret/cle.txt
- downwardAPI:
items:
- path: pod-nom
fieldRef:
fieldPath: metadata.name
- path: labels
fieldRef:
fieldPath: metadata.labels
- path: limite-memoire
resourceFieldRef:
containerName: app
resource: limits.memory
EOF
kubectl apply -f identite.yaml -n volumes && kubectl wait --for=condition=Ready pod/identite -n volumes --timeout=90s && kubectl exec identite -n volumes -- sh -c 'cd /etc/projete; for f in mode.txt secret/cle.txt pod-nom labels limite-memoire; do echo "== $f"; cat $f; echo; done'
pod/identite created
pod/identite condition met
== mode.txt
demo
== secret/cle.txt
valeur-demo
== pod-nom
identite
== labels
app="identite"
etape="1"
== limite-memoire
67108864

Five files come from three sources in a single folder. The memory limit is expressed in bytes: 67108864 is 64 Mi. kubectl describe names the sources of the volume without showing their values:

Terminal window
kubectl describe pod identite -n volumes | grep -A14 "Volumes:"
Volumes:
projete:
Type: Projected (a volume that contains injected data from multiple sources)
ConfigMapName: reglages
Optional: false
SecretName: acces
Optional: false
DownwardAPI: true
kube-api-access-86c6j:
Type: Projected (a volume that contains injected data from multiple sources)
TokenExpirationSeconds: 3607
ConfigMapName: kube-root-ca.crt
Optional: false
DownwardAPI: true
QoS Class: Guaranteed

SecretName: acces appears, but no value: describe does not display the content of a Secret, whether mounted as a volume or not. The second volume, kube-api-access-…, is the one Kubernetes adds by itself for the service account token.

Automatic updates (with a delay)

The files of a projected volume are updated without recreating the Pod, but not at the same speed depending on the source. Change a label of the Pod and wait for it to show up in the labels file:

Terminal window
kubectl label pod identite etape=2 -n volumes --overwrite && for i in $(seq 1 30); do kubectl exec identite -n volumes -- grep -q 'etape="2"' /etc/projete/labels && break; sleep 3; done; kubectl exec identite -n volumes -- cat /etc/projete/labels
pod/identite labeled
command terminated with exit code 1
app="identite"
etape="2"

The file shows etape="2" in about 3 seconds (the exit code 1 line is a first check with no result, the loop kept going). Now change the ConfigMap:

Terminal window
kubectl patch configmap reglages -n volumes -p '{"data":{"MODE":"prod"}}' && for i in $(seq 1 60); do [ "$(kubectl exec identite -n volumes -- cat /etc/projete/mode.txt)" = prod ] && break; sleep 3; done; kubectl exec identite -n volumes -- cat /etc/projete/mode.txt
configmap/reglages patched
prod

The delay before the new value arrives varies from one run to the next: 74 seconds in one measurement, 86 seconds in another. The cause is the cache of the kubelet, the Kubernetes agent on each node: it resynchronizes the mounted ConfigMaps at regular intervals and keeps their content in cache between two synchronizations.

An application that rereads its configuration file must therefore expect a delay of about a minute, not an immediate effect. A file mounted with subPath does not receive updates; this case and the propagation are detailed in ConfigMaps.

Image volumes

A volume can also mount the content of a container image, read-only, with volumes[].image.reference and pullPolicy. On Kubernetes 1.37, the feature is stable: a Pod that mounts the pinned nginx image sees its filesystem under the mount point. This is useful for providing tools or data without copying them into the application image.

Manage permissions with securityContext

A file mounted by Kubernetes belongs to root, and reading depends on the permissions of the file, and on the user and group of the process. The droits Pod runs as user 1000, group 3000, and mounts the ConfigMap with defaultMode: 0440, that is readable by the owner and its group, which are root.

Terminal window
cat > droits.yaml <<'EOF'
apiVersion: v1
kind: Pod
metadata:
name: droits
spec:
securityContext:
runAsUser: 1000
runAsGroup: 3000 # ❌ sans fsGroup, le fichier root:root en 0440 reste illisible
containers:
- name: app
image: busybox:1.38.0@sha256:a46257e06c82ad85242d0d38077d0a52d9896389ca60a1a59d3463db586e5fa4
command: ["sh", "-c", "sleep 3600"]
volumeMounts:
- name: conf
mountPath: /etc/conf
volumes:
- name: conf
configMap:
name: reglages
defaultMode: 0440
EOF
kubectl apply -f droits.yaml -n volumes && kubectl wait --for=condition=Ready pod/droits -n volumes --timeout=90s && kubectl exec droits -n volumes -- cat /etc/conf/MODE

The read is refused. The command returns:

pod/droits created
pod/droits condition met
cat: can't open '/etc/conf/MODE': Permission denied
command terminated with exit code 1

The process is neither the owner (root), nor in the root group, nor in "others" (0440 opens nothing to them). One diagnostic detail: ls -l /etc/conf/ only shows the symbolic link MODE -> ..data/MODE, whose permissions are lrwxrwxrwx. To read the real permissions of the file, add -L to follow the link, and -n to display numbers rather than names: ls -lnL /etc/conf/.

The right setting is fsGroup, which makes the files of the volume belong to a supplementary group of the process. A Pod cannot be modified on this field: delete it and recreate it with droits-corrige.yaml, which adds fsGroup: 2000 next to runAsUser and runAsGroup. The comment in the first manifest is in French and says that without fsGroup, the root:root file in 0440 remains unreadable.

Terminal window
cat > droits-corrige.yaml <<'EOF'
apiVersion: v1
kind: Pod
metadata:
name: droits
spec:
securityContext:
runAsUser: 1000
runAsGroup: 3000
fsGroup: 2000
containers:
- name: app
image: busybox:1.38.0@sha256:a46257e06c82ad85242d0d38077d0a52d9896389ca60a1a59d3463db586e5fa4
command: ["sh", "-c", "sleep 3600"]
volumeMounts:
- name: conf
mountPath: /etc/conf
volumes:
- name: conf
configMap:
name: reglages
defaultMode: 0440
EOF
kubectl delete pod droits -n volumes --wait=true && kubectl apply -f droits-corrige.yaml -n volumes && kubectl wait --for=condition=Ready pod/droits -n volumes --timeout=90s && kubectl exec droits -n volumes -- sh -c 'ls -lnL /etc/conf/MODE; cat /etc/conf/MODE'
pod "droits" deleted from volumes namespace
pod/droits created
pod/droits condition met
-r--r----- 1 0 2000 4 Nov 11 16:01 /etc/conf/MODE
prod

The file now belongs to group 2000 with the -r--r----- permissions, and cat returns the value of the ConfigMap. fsGroup also adds read access for the group when the mode did not grant it: a file in 0400 becomes readable as 0440 for group 2000. The details of securityContext are in Security context.

hostPath: access to the node's filesystem

A hostPath volume mounts a folder of the node into the Pod. It is useful for system agents, and dangerous for an application: the Pod reads, sometimes writes, the disk of the node that hosts it.

Terminal window
cat > hote.yaml <<'EOF'
apiVersion: v1
kind: Pod
metadata:
name: hote
spec:
containers:
- name: app
image: busybox:1.38.0@sha256:a46257e06c82ad85242d0d38077d0a52d9896389ca60a1a59d3463db586e5fa4
command: ["sh", "-c", "sleep 3600"]
volumeMounts:
- name: noeud
mountPath: /noeud
readOnly: true
volumes:
- name: noeud # ❌ hostPath donne accès au système de fichiers du nœud
hostPath:
path: /etc
type: Directory
EOF
kubectl apply -f hote.yaml -n volumes && kubectl wait --for=condition=Ready pod/hote -n volumes --timeout=90s && kubectl exec hote -n volumes -- cat /noeud/hostname
pod/hote created
pod/hote condition met
demo-control-plane

The Pod read the name of the kind node, demo-control-plane, in the node's /etc. Kubernetes raised no refusal because this namespace enforces no Pod Security restriction. For data that must last, use a PersistentVolumeClaim instead, that is the request for persistent storage that a Pod makes to Kubernetes (see Storage).

Which volume type should you choose?

You have now seen the main volume types. To pick one, start from what the application has to do: exchange files between containers, read a configuration, know the metadata of its Pod, or keep data when the Pod disappears. The table maps each need to the matching type, with the reason for the choice.

NeedVolume typeWhy
Exchange files between the containers of a PodemptyDirEmpty folder created with the Pod, shared by all its containers, deleted with it
A fast, temporary workspace, without writing to diskemptyDir with medium: Memorytmpfs filesystem in RAM; it counts toward the container's memory, so bound it with sizeLimit
Provide a configuration file or a secret to the applicationconfigMap or secretThe keys become files, updated with a delay, except with subPath
Gather ConfigMap, Secret and metadata in a single folderprojectedSeveral sources under the same mount point
Read the name, labels or limits of the Pod from the applicationdownwardAPI (alone or in a projected)The Pod metadata is exposed as files
Get the files of an image without copying them into the applicationimage volumeThe content of the image is mounted read-only
Read a file of the node itselfhostPathAvoid it outside system cases: the Pod depends on the node and reaches its filesystem
Keep data beyond the life of the PodPersistentVolumeClaimThe storage lives independently of the Pod, see Storage

If the data must survive the Pod, no volume of this lesson fits: use a PersistentVolumeClaim. In the other cases, take the most restricted type that meets the need, and keep hostPath for the system components that really have to read the node.

Clean up the cluster

Deleting the namespace removes all the Pods, the ConfigMap and the Secret of the lesson. The /tmp/id-avant.txt file lives on your workstation and is removed separately:

Terminal window
kubectl delete namespace volumes && rm -f /tmp/id-avant.txt
namespace "volumes" deleted

Troubleshooting

SymptomLikely causeWhat to do
Permission denied on a ConfigMap or Secret fileThe group of the process is not in the permissions of the fileAdd fsGroup and recreate the Pod; read the permissions with ls -lnL
Read-only file systemThe mount carries readOnly: trueWrite from a container that mounts the volume read-write
The value of a mounted ConfigMap does not changeResynchronization delay of the kubelet, or file mounted with subPathWait about a minute; avoid subPath if updates matter
The data disappeared after kubectl delete podAn emptyDir disappears with the PodUse a PersistentVolumeClaim

Put it into practice

In the lab, you make one container read what another writes, and nothing else. Two containers of the same Pod share an ephemeral volume, and a file written outside the volume must stay invisible to the reader. The validation checks three things: the volume is mounted at the same path in both containers, the reader sees the producer's file, and the file written outside the volume stays invisible to it.

Key takeaways

  1. A volume is declared in the Pod's spec.volumes and mounted in each container with volumeMounts.
  2. An emptyDir shares its folder between containers; anything written outside the volume stays invisible to the other containers.
  3. The emptyDir survives a container restart and disappears with the Pod; a container's filesystem survives neither.
  4. readOnly: true is a setting of the mount, specific to each container.
  5. An emptyDir in memory (medium: Memory) is a tmpfs counted in memory; bound it with sizeLimit.
  6. A projected volume gathers ConfigMap, Secret and downwardAPI in a single folder; kubectl describe shows no Secret value.
  7. Projected files are updated without recreating the Pod, with a delay (about 3 s for a label, about a minute for a ConfigMap).
  8. ls -l shows the symbolic link of a mounted file; ls -lnL shows its real permissions, and fsGroup fixes a read refusal.

Test your knowledge

This quiz covers what a volume shares and isolates, what survives a restart, and the diagnosis of a read refusal. Allow five minutes and aim for 80%; below that, reread "emptyDir: temporary sharing between containers".

Knowledge check

Check what you have learned with this interactive quiz

7 questions
5 min
80% to pass

How it works

  • The timer starts when you click Start
  • Multiple choice, true/false and short answer questions
  • You can move between questions
  • Detailed results are shown at the end

Starts the quiz and the timer