Chapter 9: Adding volumes for storage, configuration, and metadata

Introduction

The introduction explains why storage volumes commonly accompany containers in a pod: they hold data and let containers share files.

• Purpose of pod volumes: Explain that volumes accompany containers in a pod to store data for the pod’s lifetime or beyond and to share files among containers in that pod.
  Why it matters: This gives you the basic reason to add a volume to a pod.

Key terms: pod, containers, storage volumes

9.1 Introducing volumes

This section explains why container file changes disappear on restart and introduces pod volumes as a way to preserve files by mounting them into a container.

• Container filesystems and restarts: Explain that containers in the same pod have separate filesystems supplied by their images, and why changes made to a container’s files are lost when it is terminated and restarted.
  Why it matters: This explains why an application cannot rely on changes to its container filesystem surviving a restart.
• Volumes and filesystem mounting: Describe how adding a volume to a pod and mounting it into a container can preserve all or part of the filesystem across container restarts. Explain what mounting makes available in the container’s file tree.
  Why it matters: Mounting a volume gives an application a place for files it needs after its container restarts.

Key terms: pod, container image, isolated filesystem, volume, mounting, file tree

9.1.1 Understanding when to use a volume

The section uses a Quiz service to show why MongoDB data must be stored outside its container to survive container recreation.

• Quiz service data flow: Describe how the Quiz API and MongoDB work together in the initial pod, and how adding a question makes it available through the API.
  Why it matters: This establishes what data the service needs before testing whether that data survives.
• MongoDB container data loss: Trace what happens to the stored questions when the MongoDB container is recreated, and explain why the service needs a volume.
  Why it matters: A working database is not enough if replacing its container erases the questions it stored.

Key terms: Quiz API, MongoDB, questions collection, kiada database, container’s filesystem, container image, volume, container restarts

9.1.2 Understanding how volumes fit into pods

This section explains how pod volumes are mounted, what data they can retain or share, and how volume types determine where that data comes from.

• Pod volume life cycle: Explain why a volume can retain files across a container restart even though files written elsewhere in the container are lost.
  Why it matters: This distinction tells you where an application must write files it needs after a container restart.
• Selective file retention: Justify why an application might preserve its state in a volume but leave locally cached files out of it.
  Why it matters: A volume should preserve the files an application needs without defeating a useful fresh start.
• Multiple and selective mounts: Describe how a pod’s volumes can be mounted in its containers and why containers need not all receive the same volumes.
  Why it matters: You can give each container access to the files it needs without exposing every volume to every container.
• Shared container files: Explain how mounting one volume in multiple containers lets them work on the same files, including different mount locations and read/write settings.
  Why it matters: A shared volume lets specialized containers cooperate while keeping unnecessary write access away from a reader.
• Persistence and sharing across pods: Distinguish the life of a pod volume from the life of its underlying storage, and explain when separate pods can use the same stored data.
  Why it matters: Pod replacement need not erase application data, but sharing that data requires storage with suitable attachment capabilities.
• Volume type choices: Describe what specifying a volume type determines, using examples from the types introduced here, and explain the role of persistentVolumeClaim for external storage.
  Why it matters: The volume type tells you whether a mount supplies temporary space, existing files, configuration, or access to external storage.

Key terms: volume, pod life cycle, container restart, container image, application’s state, locally cached data, self-healing capability, crash loop, pod volumes, mount

9.2 Using an emptyDir volume

This section introduces emptyDir as an initially empty volume that keeps files for a pod’s lifetime and supports temporary writes or file sharing within a pod.

• emptyDir lifetime and uses: Explain when an emptyDir volume is useful and how long its files remain available. Distinguish sharing between containers in one pod from sharing between different pods.
  Why it matters: It helps you choose temporary storage without mistaking it for storage shared across pods.

Key terms: emptyDir, volume, pod, read-only

9.2.1 Persisting files across container restarts

This subsection shows how to mount an emptyDir volume for MongoDB data, what survives a container restart, and how to configure the volume’s storage medium and size.

• EmptyDir volume and mount: Describe the two pod-manifest changes that make MongoDB write its files to an emptyDir volume rather than the container’s filesystem.
  Why it matters: Both the volume definition and the mount are needed for MongoDB to put its data in the volume.
• EmptyDir storage and lifespan: Explain where emptyDir files reside and distinguish what happens to them when a container restarts versus when the pod is deleted.
  Why it matters: An emptyDir protects files from container restarts, not from deletion of the pod.
• Memory medium and size limit: Describe how to put an emptyDir volume in memory, why that can be useful, and how its size can be limited.
  Why it matters: The storage medium affects speed and exposure of sensitive files, while a size limit matters especially for memory-backed volumes.

Key terms: emptyDir, spec.volumes, volumeMounts, mountPath, quiz-data, /data/db, container restart, pod deletion, host node’s filesystem, medium

9.2.2 Initializing an emptyDir volume

This section shows how to populate an emptyDir volume before the quiz application starts, using an init container or short file contents defined in the Pod manifest.

• Init container database setup: Trace how an init container places a database initialization script in a shared emptyDir volume before MongoDB starts, and explain why this populates a newly empty quiz database.
  Why it matters: This lets each new quiz pod populate its empty database without manually inserting questions or rebuilding the MongoDB image.
• Inline volume file contents: Describe the alternative of defining a short file’s contents directly in the Pod manifest to initialize an emptyDir volume.
  Why it matters: A small configuration file can be supplied through a volume without creating another resource just to hold its contents.

Key terms: emptyDir volume, init container, initdb volume, insert-questions.js, /docker-entrypoint-initdb.d/, quiz-data, pod manifest, inline

9.2.3 Sharing files between containers

Shows how an emptyDir volume lets a quote-writing container and an Nginx container share a file, and notes a startup timing issue.

• Shared quote file volume: Explain how the quote pod uses one volume to let quote-writer update a file that nginx serves, even though the volume is mounted at different paths in the two containers. Describe how fetching the quote again after a minute, or reading it from both containers, demonstrates the sharing.
  Why it matters: A shared volume lets one container produce a file for another container to use without requiring identical filesystem paths.
• Initial quote timing: Explain why nginx may briefly run before a quote is available and how an init container could prevent that.
  Why it matters: Sharing a volume does not guarantee that the file already exists when a container first tries to serve it.

Key terms: emptyDir volume, quote-writer, nginx container, shared volume, init container, initial quote

9.3 Mounting a container image as a volume

This section motivates using a container image to provide prepared files to other containers and explains why the ImageVolume feature gate may need to be enabled.

• Prepared files from images: Explain why a pod might use a container image to provide prepared files to another container, and how this simplifies the quiz pod’s earlier copy-and-share approach.
  Why it matters: It clarifies the problem that mounting an image as a volume is meant to solve.
• ImageVolume feature gate: State why an administrator may need to enable the ImageVolume feature gate before the simpler approach works, even if its API fields are visible.
  Why it matters: Visible configuration fields do not guarantee that the cluster can use the feature.

Key terms: container image, volume, model weights, ImageVolume feature gate, feature gate, cluster administrator

9.3.1 Introducing the image volume type

This subsection explains how a read-only OCI image volume replaces an init-container-populated emptyDir volume for supplying MongoDB startup data.

• Image volume contents and access: Explain that an image volume exposes files from an OCI image to other containers in the same pod, which can read but not write those files.
  Why it matters: It lets you recognize when an image can supply files to a container without running that image as an application.
• Quiz questions volume replacement: Describe how the quiz pod supplies insert-questions.js to MongoDB with an image volume instead of an emptyDir volume populated by an init container.
  Why it matters: This example shows how an image volume can eliminate a container whose only job was to copy files into a volume.
• Image pull and volume timing: Explain why the questions image is pulled before the pod’s container images, and relate that order to when pod volumes are created.
  Why it matters: The observed pull order makes sense once you know the volume must be prepared before containers start.

Key terms: image volume, OCI image, container image, emptyDir volume, init container, insert-questions.js, quiz-questions image, pod volumes

9.4 Accessing files on the worker node’s filesystem

This section explains why system-level pods may need access to a worker node’s filesystem and identifies hostPath as the volume type that provides it.

• Node filesystem access exception: Explain why most pods should not access files on their host node, why system-level pods may need to, and which volume type makes that access possible.
  Why it matters: It helps distinguish ordinary pods from the system-level pods that need access to their host node.

Key terms: system-level pods, node’s filesystem, hostPath volume type

9.4.1 Introducing the hostPath volume

Introduces hostPath volumes as node-local filesystem mounts, explaining when they are useful, why they are unsuitable for movable database pods, and the security risk they create.

• Node-local hostPath access: Explain that a hostPath volume points to a particular file or directory on a worker node, so pods using the same path share files only when they run on that node.
  Why it matters: The files a pod sees through hostPath depend on which node runs it.
• Appropriate hostPath uses: Describe why hostPath can serve pods that need node-generated files, such as system-level logs, but is a poor choice for database data unless the database pod always runs on the same node.
  Why it matters: Choosing hostPath requires accounting for the pod’s dependence on a particular node.
• hostPath privilege risk: Explain why unrestricted hostPath access is dangerous, using the Docker socket example to show how a container could run commands on its host node as root.
  Why it matters: A filesystem mount can become a route to control over the node, not merely a way to read application files.

Key terms: hostPath volume, host node, worker node, system-level logs, privileged pods, Docker socket file

9.4.2 Using a hostPath volume

This subsection uses a hostPath volume to show how a pod can access a worker node’s filesystem, then explains hostPath type checks and their security implications.

• Host filesystem access through hostPath: Explain that a hostPath volume specifies a path on the worker node and makes that path accessible inside the pod. Describe why mounting the node’s root directory is dangerous when the container runs as root.
  Why it matters: Mounting a host path can give a container far more access to its worker node than intended.
• hostPath type checks and creation: Describe how specifying a hostPath type checks that the host path is the expected kind of file or directory, what happens when it does not match, and the stated permissions and ownership when a FileOrCreate or DirectoryOrCreate path must be created.
  Why it matters: A type check can catch a host path that is not what the container expects, and create types determine the permissions of new paths.

Key terms: hostPath volume, host node, worker node, hostPath type, FileOrCreate, DirectoryOrCreate, pod events, Kubelet

9.5 ConfigMap, Secret, Downward API, and projected volumes

Introduces file-based delivery of configuration and sensitive data through volumes, using the Envoy sidecar to explain why these files should not be baked into an image.

• File-based Envoy configuration: Explain why the Envoy configuration file, TLS certificate, and private key should be supplied as files from a ConfigMap and Secret rather than stored in the container image. Distinguish which source is appropriate for the configuration and which for the certificate and key.
  Why it matters: Keeping these files outside the image makes updates easier and separates ordinary configuration from sensitive credentials.

Key terms: ConfigMap, Secret, volume, Envoy sidecar, TLS certificate, private key

9.5.1 Using a configMap volume to expose ConfigMap entries as files

This section shows how to expose ConfigMap entries as files in a pod, including what happens when the ConfigMap is missing, how file updates behave, and how to include only selected entries.

• ConfigMap entries as files: Explain when to use a configMap volume and how it makes ConfigMap entries available to a container.
  Why it matters: It lets an application read configuration files supplied through a ConfigMap without putting their contents in environment variables.
• Missing ConfigMap startup behavior: Distinguish the effect of a missing required ConfigMap on a pod volume from the effect of marking that volume optional.
  Why it matters: A missing configuration source can stop an entire pod, even when only one container mounts the volume.
• ConfigMap file update behavior: Distinguish how ConfigMap changes affect files supplied by a configMap volume versus injected environment variables.
  Why it matters: The way configuration is supplied determines whether a running container can see changed values in its files.
• Selective entry projection: Describe how to include only selected ConfigMap entries as files in a configMap volume.
  Why it matters: It keeps files a container does not need out of its mounted directory while allowing the pod to use one ConfigMap.

Key terms: configMap volume, ConfigMap entries, mount, optional: true, environment variables, items, key, path

9.5.2 How configMap volumes work

This section explains how configMap volume mounts affect existing files, how Kubernetes updates volume files atomically, and why subPath mounts behave differently.

• Volume Mounts and Existing Files: Explain what happens to files already present in a container-image directory when a volume is mounted there, and how mounting one ConfigMap file with subPath avoids hiding them.
  Why it matters: A mount over a directory such as /etc can hide files an application needs to run.
• Atomic ConfigMap File Updates: Trace how symbolic links let Kubernetes replace the files in a configMap volume together when the ConfigMap changes.
  Why it matters: Atomic replacement prevents applications from reading a partially updated configuration.
• SubPath Update Tradeoff: Explain why a ConfigMap file mounted with subPath does not update when the ConfigMap changes, and describe the symbolic-link alternative given here.
  Why it matters: The way you mount a single configuration file determines whether later ConfigMap changes reach it.

Key terms: configMap volume, mountPath, subPath, symbolic links, ..data, timestamped directory, atomic updates, symbolic link

9.5.3 Using Secret volumes

This section shows how to mount a Secret as files in a pod, what the container reads from those files, and why this can replace a custom image.

• Secret volume and mount: Describe how to expose the kiada-tls Secret’s certificate and private key to the envoy container by defining a secret volume and a volumeMount. Distinguish the secret volume definition from the similar configMap volume definition.
  Why it matters: This lets the container read the certificate and key as files without putting them in its image.
• Decoded Secret file contents: Explain what a container reads from a secret volume when the Secret entry appears Base64-encoded in the Secret object’s YAML.
  Why it matters: The application can use the mounted certificate and key directly.
• External files and image maintenance: Explain why sourcing the Envoy configuration, TLS certificate, and private key from outside the image allows the kiada-ssl Pod to use a generic Envoy image.
  Why it matters: Separating these files from the image reduces the number of custom images to maintain.
• Secret volume storage and availability: State where secret volume files are stored and describe how the optional field affects pod startup when the referenced Secret is missing.
  Why it matters: These details affect both the exposure of sensitive files and whether a pod can start without its Secret.

Key terms: secret volume, volumeMount, secretName, kiada-tls Secret, Secret entry, Base64-encoded, kiada-ssl-proxy, envoyproxy/envoy, container image, tmpfs

9.5.4 Setting file permissions and ownership in a secret/configMap volume

This section explains how to set and inspect file permissions in Secret and ConfigMap volumes, and how to keep restricted files accessible to container processes.

• Volume file permission settings: Explain the default permissions for files in Secret and ConfigMap volumes and how to change permissions for all files or individual files.
  Why it matters: These settings let you restrict access to mounted configuration and secrets without accidentally assigning unintended permissions.
• Mounted file permission inspection: Describe why the displayed permissions of a Secret or ConfigMap volume's symbolic links do not show the effective file permissions, and how to inspect the targets.
  Why it matters: Checking the target avoids mistaking a symbolic link's displayed permissions for the file's actual access rules.
• Restricted access through group ownership: Explain why tighter file permissions can prevent a container process from reading a volume file and how the pod's fsGroup setting addresses that problem.
  Why it matters: Restricting a private key is useful only if the process that needs it can still read it.

Key terms: secret volume, configMap volume, defaultMode, mode, 0644, symbolic links, ls -lL, target file permissions, UID, GID

9.5.5 Using a downwardAPI volume to expose Pod metadata as files

Shows how to expose Pod metadata as files through a downwardAPI volume and how to reference Pod and container resource fields in that volume.

• Pod Name File Projection: Describe how a downwardAPI volume can place the Pod’s name in a file inside a container, using the section’s manifest example.
  Why it matters: It lets a container read its Pod name from a file rather than an environment variable.
• Downward API Field References: Distinguish references to Pod fields from references to container resource fields in downwardAPI volume items, and explain the extra information a resource reference needs.
  Why it matters: The correct reference identifies both the value to project and, for a resource value, the container it belongs to.

Key terms: downwardAPI volume, metadata.name, volumeMount, fieldRef, resourceFieldRef, containerName, divisor

9.5.6 Using projected volumes to combine volumes into one

This section explains how projected volumes combine files from multiple sources in one directory, then describes the automatically added kube-api-access projected volume.

• Projected volume purpose: Explain why a projected volume is useful when files from multiple ConfigMaps, Secrets, or the Downward API must appear in one directory, including the drawback of using subPath instead.
  Why it matters: It explains why combining sources in a projected volume can be preferable to mounting individual files with subPath.
• Combined Envoy configuration files: Describe how the kiada-ssl example replaces separate ConfigMap and Secret volumes with one projected volume and where their selected entries appear.
  Why it matters: The example shows how one mount gives a container selected files from both configuration and secret sources.
• Built-in API access volume: Describe the automatically added kube-api-access projected volume and explain why a pod that does not need Kubernetes API access might disable its token mount.
  Why it matters: It helps explain an extra volume in a pod manifest and why unnecessary API access should be avoided.

Key terms: projected volume, subPath, ConfigMap, Secret, Downward API, etc-envoy, kiada-ssl-config, kiada-tls, read-only, kube-api-access

9.6 Other volume types at a glance

This section surveys additional Kubernetes volume types, contrasting persistentVolumeClaim and ephemeral volumes and explaining why CSI-backed storage is usually accessed through those abstractions.

• Persistent and ephemeral volume requests: Distinguish a persistentVolumeClaim volume from an ephemeral volume by describing how each obtains storage and what happens when the pod is deleted.
  Why it matters: The distinction helps you choose whether storage should outlive a pod.
• Storage drivers and volume abstractions: Explain why direct references to technology-specific volume types have largely been deprecated, and distinguish direct CSI-driver configuration from the recommended claim-based volume types.
  Why it matters: Claim-based volumes usually keep a pod less tied to a particular storage technology.

Key terms: persistentVolumeClaim, ephemeral, PersistentVolume, csi, Container Storage Interface, CSI driver

9.7 Summary

Summarizes how pod volumes provide mounted storage and files, and distinguishes the uses and risks of the volume types covered in the chapter.