Q: What is a projected volume in Kubernetes?
A projected volume in Kubernetes maps several existing volume sources into one directory, so a container sees a ConfigMap, a Secret, downward API fields and a ServiceAccount token under a single mount path.
Want to master this scenario in a live sandbox? KodeKloud's CKA & CKAD Hands-On Certification Track covers this exact problem with hands-on terminal drills.
🛠️ Production Runbook & Step-by-Step Resolution
Direct Answer: A <strong>projected volume in Kubernetes</strong> maps several existing volume sources into one directory, so a container sees a ConfigMap, a Secret, downward API fields and a ServiceAccount token under a single mount path. It is the mechanism behind the default ServiceAccount token volume. Interviewers ask about it to check that you know the supported source types, how files are updated, and why it is the preferred way to deliver short-lived, audience-bound tokens.
Mental model: one mount, many sources
Instead of mounting three volumes at three paths, you declare one volume with a list of sources.
- Supported sources:
secret,configMap,downwardAPI,serviceAccountToken, andclusterTrustBundle(beta in 1.29 and newer, behind a feature gate, so check your version). - Same namespace: Secrets and ConfigMaps must exist in the pod's namespace.
- Unique paths: every file path across all sources must be distinct, otherwise the pod fails to start with a conflict.
- Why use it: a single directory for an application that expects its config, credentials and identity token together, and fine-grained control over file names and modes.
- Compared with separate volumes: mounting a Secret, a ConfigMap and downward API files as separate volumes needs three mount paths; projection gives one coherent tree and a single place to set default modes.
Hands-on: projected volume in Kubernetes with four sources
Combine a ConfigMap, Secret, downward API labels and a short-lived token into /etc/app.
apiVersion: v1
kind: Pod
metadata:
name: my-app
namespace: prod
labels:
app: my-app
spec:
serviceAccountName: my-sa
containers:
- name: app
image: registry.example.com/my-app:1.0.0
volumeMounts:
- name: app-config
mountPath: /etc/app
readOnly: true
volumes:
- name: app-config
projected:
defaultMode: 0440
sources:
- configMap:
name: app-settings
items: [{key: settings.yaml, path: settings.yaml}]
- secret:
name: app-credentials
items: [{key: db-password, path: secrets/db-password}]
- downwardAPI:
items:
- path: labels
fieldRef: {fieldPath: metadata.labels}
- serviceAccountToken:
path: token
audience: https://vault.example.com
expirationSeconds: 3600
- items: select specific keys and rename them with
path; withoutitemsall keys are projected. - mode: per-file permissions via
mode, withdefaultModefor the whole volume. - Token source:
serviceAccountTokentakesaudience,expirationSecondsandpath. - readOnly: mount it read-only in the container, as the contents are managed by the kubelet.
- Typical use case: a service that reads
/etc/app/settings.yaml, a password file and an identity token from the same configuration directory, without the application knowing they came from three objects.
Verify the projected files and their updates
Look inside the container to confirm layout, permissions and refresh behaviour.
kubectl -n prod exec my-app -- ls -lR /etc/app
kubectl -n prod exec my-app -- cat /etc/app/labels
kubectl -n prod describe pod my-app | sed -n '/Volumes:/,/QoS/p'
- List files:
kubectl exec my-app -n prod -- ls -lR /etc/app. Expect symlinks into a timestamped data directory, which is how updates are swapped atomically. - Update propagation: ConfigMap and Secret changes appear after the kubelet sync period plus cache delay, typically within a minute or so. This is eventual, not instant.
- subPath caveat: files mounted with
subPathare never updated after start. - Token refresh: the kubelet rewrites the token file before expiry; check the
expclaim over time. - Atomic updates: the kubelet writes a new timestamped directory and flips a symlink, so readers never observe a half-written set of files.
- Permissions in the container: files appear with the modes you set, and
fsGroupin the pod securityContext adjusts group ownership so a non-root process can read them.
Failure modes and edge cases
Most projected volume issues show up as pods stuck in ContainerCreating.
- Missing source: a missing Secret or ConfigMap leaves the pod in
ContainerCreatingwith a MountVolume.SetUp failed event, unless the source is markedoptional: true. - Path collision: two sources writing the same
pathare rejected. - Env vars do not update: values copied into environment variables never refresh; only mounted files do.
- Big payloads: ConfigMaps and Secrets have a size cap of about 1 MiB each; do not project large blobs.
- Optional sources: mark non-critical sources as
optional: trueso the pod still starts if they are missing, and handle absence in the application. - Order is not guaranteed to matter: do not rely on one source overriding another; give every file a unique path and treat the volume as a union.
Production practice: when to choose it
Use projected volumes when they remove glue code, not by default.
- Workload identity: project audience-scoped tokens for Vault, cloud IAM federation or service meshes.
- Hot reload: pair file projection with an app that watches files, or a reloader sidecar.
- Least privilege: project only the keys the container needs using
items. - Security: set restrictive modes and run as non-root with
fsGroupwhere file ownership matters. - Observe the effect: track mount failures through pod events and alert on pods stuck in ContainerCreating for longer than a normal image pull.
- Cost of change: adding a new source later only needs a manifest edit and a rollout, which is cheaper than writing sidecar code to fetch each value.
- A projected volume merges Secrets, ConfigMaps, downward API fields and ServiceAccount tokens into one directory.
- I verify with kubectl exec ls, pod events for mount errors, and watch that file updates arrive without subPath.
- I automate token audiences and expirations in manifests and keep only required keys in the projection.
Senior hiring managers and bar raisers evaluate how you prioritize during outages. Avoid these common anti-patterns:
- Using subPath with a projected source and expecting updates subPath mounts are a snapshot and never receive kubelet refreshes.
- Assuming environment variables follow ConfigMap or Secret updates Env vars are fixed at container start; only files change, so a restart or reload is needed.
- Reusing the same path in two sources Kubernetes rejects the pod because files would collide in the same directory.
- Projecting the whole Secret instead of selected keys It widens exposure and file clutter; items narrows what the container can read.