Why do image files vanish after mounting a Kubernetes volume?

Your image ships three config files, but the container sees only one. The image config has three files. After the ConfigMap mount, the Pod view shows settings.yaml only. Then logging.yaml is missing, and the app crashes. The image didn't change. The mount did it.

Here's the cause, in the Deployment. A ConfigMap is Kubernetes storing config files, and web-config holds only settings.yaml. A volumeMount attaches that storage inside the container at a path. Look at mountPath: it's /app/config, the same directory the image already uses for its three files.

Start with a container and no mount. Its filesystem is the image layers, which are read-only, with a thin writable layer stacked on top. The app sees them as one filesystem. So looking at /app/config, it finds all three files: settings.yaml, logging.yaml, and routes.yaml.

Now the ConfigMap mount is placed on /app/config, and it covers the whole directory. The image layers and writable layer are still there underneath, but at that path the app sees only one file, settings.yaml. A mount works like a lid over a directory. The image files sit underneath, hidden.

A mount replaces the view of the directory. It never merges, so there's no file-by-file mixing. It's applied before the app starts, so the app never sees the originals. And the image itself stays untouched, with every file still inside.

The same rule applies to a second case. Here we mount an emptyDir at /app/data. An emptyDir is a scratch folder that starts out empty. The image's seed.db is still there, but it's hidden under the mount, so the app sees an empty folder and finds no data.

On a laptop, a Docker named volume starts empty, and on first use Docker copies the image's content into it. So seed.db shows up. A Kubernetes volume, like emptyDir or a ConfigMap, is mounted as-is. Nothing is copied from the image, and the image files stay hidden underneath.

That copy only happens with Docker named volumes, so don't rely on it. Kubernetes never copies image files in. Let's look at three fixes.

The first fix is to mount the ConfigMap somewhere the image doesn't use, like /app/config/overrides. The lid lands on an empty spot, so the three image files in /app/config stay visible. The trade-off is that your app must be told to read its settings from that new path.

With subPath, the mountPath points at a single file, settings.yaml, instead of the whole directory. Only that file is overlaid, so logging.yaml and routes.yaml from the image stay visible. The trade-off is that subPath mounts don't receive ConfigMap updates automatically. You'd need to restart the Pod.

Here's the third fix, for the emptyDir case. The kubelet creates an empty emptyDir, then starts an init container from the same image. That container mounts the volume at another path, so seed.db is still visible to copy. When it exits successfully, the app container starts and reads seed.db. The trade-off is extra startup work in every new Pod.

To diagnose this, compare three views. First, list the path inside the running Pod: only settings.yaml appears. Next, list the same path in the image with docker run: all three files show up. Then grep the Pod spec for volumeMounts, and find which mountPath targets that directory. That's your culprit.

A mount is a lid over a directory; image files sit underneath. Before you deploy, check every mountPath against directories the image already populates.