Introduction

When Kubernetes mounts a volume into a container path, the mounted volume hides the files that were originally baked into that directory in the image. That behavior is often surprising the first time you mount onto a path that already contains defaults, scripts, or configuration files.

What Actually Happens

A volume mount does not merge directory contents with the image filesystem. It overlays the mount path. From inside the container, you see the mounted volume’s contents at that path, not the original files from the image layer underneath.

That means this image layout:

• image contains /app/config/default.yaml
• pod mounts a volume at /app/config

results in the original default.yaml being hidden while the volume is mounted.

Example Of The Problem

This pod mounts an emptyDir on a path that already exists in the image.

1apiVersion: v1
2kind: Pod
3metadata:
4  name: demo
5spec:
6  containers:
7    - name: app
8      image: busybox
9      command: ["sh", "-c", "ls -la /data && sleep 3600"]
10      volumeMounts:
11        - name: work
12          mountPath: /data
13  volumes:
14    - name: work
15      emptyDir: {}

If the image had files in /data, they would not be visible after the mount because the emptyDir now occupies that path.

Safer Patterns

There are three common workarounds.

1. Mount Somewhere Else

The simplest option is to mount the volume at a different path and let the application read from that path explicitly.

volumeMounts:
  - name: config
    mountPath: /mounted-config

This avoids hiding image content and is the least surprising design.

2. Use subPath

If you only need one file or subdirectory from the volume, subPath can mount a narrower target instead of replacing the whole directory.

1volumeMounts:
2  - name: config
3    mountPath: /app/config/custom.yaml
4    subPath: custom.yaml

This is useful when the image already contains defaults and you only want to replace one file.

3. Copy Image Files Into A Writable Volume

If the application must write into a directory that also needs default image content, copy those defaults into a writable volume during startup. An initContainer is the cleanest way.

1apiVersion: v1
2kind: Pod
3metadata:
4  name: app-with-init
5spec:
6  initContainers:
7    - name: seed-data
8      image: myapp:latest
9      command: ["sh", "-c", "cp -R /app/defaults/. /work/"]
10      volumeMounts:
11        - name: workdir
12          mountPath: /work
13  containers:
14    - name: app
15      image: myapp:latest
16      volumeMounts:
17        - name: workdir
18          mountPath: /app/defaults
19  volumes:
20    - name: workdir
21      emptyDir: {}

Now the container sees the copied defaults in the mounted volume instead of losing them.

Choose Based On Ownership

The right pattern depends on who owns the directory semantics:

• if the app can read another path, mount elsewhere
• if only one file must be replaced, use subPath
• if the app expects writable seeded content, copy defaults into a volume first

Trying to force Kubernetes to merge the image directory with the mounted volume is the wrong mental model.

Common Pitfalls

The most common mistake is assuming the mount will append files to the existing image directory. It will not. The original directory contents are hidden while the mount exists.

Another mistake is mounting a ConfigMap or Secret onto an application directory that already contains required startup files. The app then fails because its bundled files disappeared from view.

A third issue is writing data into a path that is still part of the image filesystem. If persistence or sharing is required, plan the volume layout explicitly rather than relying on the image layer.

Summary

• A Kubernetes volume mount hides the existing image contents at that mount path.
• Volumes do not merge automatically with files already inside the container image.
• Use a different mount path, subPath, or an initContainer copy step depending on the use case.
• Mounting over a populated directory is often the root cause of missing files at runtime.
• Design the application paths with volume ownership in mind instead of expecting overlay merging.