Read-Only Root Filesystem in Docker and Kubernetes (readOnlyRootFilesystem)
Table of Contents
Updated November 2026: Refreshed for Docker 29, Compose v5 and Kubernetes 1.37: added Compose read_only/tmpfs, memory-backed emptyDir with sizeLimit, a Pod Security Standards “restricted” example and a diagram; all Docker commands re-run against current nginx:alpine.
A read-only root filesystem is one of the cheapest ways to harden a container. If an attacker gets code execution inside it, they can’t drop binaries, patch config files or tamper with the application. Most applications still need to write somewhere (PID files, caches, temp files), so the pattern is always the same: make the root filesystem read-only and mount small, writable scratch areas exactly where the application needs them.
Read-only root filesystem with writable tmpfs or emptyDir mounts
I’ll walk through this with NGINX, first in Docker, then in Docker Compose and finally in Kubernetes.
Read-only filesystem in Docker: --read-only
docker run has a --read-only flag that mounts the container’s root filesystem read-only. A quick test with ubuntu:
docker run --rm --read-only ubuntu touch /hello
touch: cannot touch '/hello': Read-only file system
That’s fine for a container that never writes. NGINX, however, does:
docker run -d --name web -p 8080:80 --read-only nginx:alpine
docker logs web
...
10-listen-on-ipv6-by-default.sh: info: can not modify /etc/nginx/conf.d/default.conf (read-only file system?)
/docker-entrypoint.sh: Configuration complete; ready for start up
[emerg] 1#1: mkdir() "/var/cache/nginx/client_temp" failed (30: Read-only file system)
nginx: [emerg] mkdir() "/var/cache/nginx/client_temp" failed (30: Read-only file system)
The info line about default.conf is harmless: the entrypoint just can’t add the IPv6 listen directive, and I don’t want runtime changes to the config anyway. The [emerg] line is the real problem. NGINX needs a writable /var/cache/nginx.
Writable paths with --tmpfs
A tmpfs mount is an in-memory filesystem that lives as long as the container. It isn’t persisted, and it isn’t shared with other containers. Exactly what we want for scratch data. Let’s add one for the cache directory:
docker rm -f web
docker run -d --name web -p 8080:80 --read-only \
--tmpfs /var/cache/nginx \
nginx:alpine
docker logs web
...
[emerg] 1#1: open() "/run/nginx.pid" failed (30: Read-only file system)
nginx: [emerg] open() "/run/nginx.pid" failed (30: Read-only file system)
One step further. Now NGINX wants to write its PID file to /run (/var/run is a symlink to it on Alpine). Add a second tmpfs:
docker rm -f web
docker run -d --name web -p 8080:80 --read-only \
--tmpfs /var/cache/nginx \
--tmpfs /run \
nginx:alpine
docker logs web
...
[notice] 1#1: nginx/1.31.9
[notice] 1#1: start worker processes
NGINX is up, and the rest of the filesystem is still locked down:
curl -s localhost:8080 | grep title
<title>Welcome to nginx!</title>
docker exec web touch /etc/nginx/nginx.conf
touch: /etc/nginx/nginx.conf: Read-only file system
docker exec web touch /run/ok # works
Docker mounts a tmpfs with rw,nosuid,nodev,noexec by default, so nothing written there can be executed. The size is unbounded unless you set it, which I recommend for anything that isn’t tiny: --tmpfs /var/cache/nginx:size=16m. If you need more options (mode, uid), the long form is --mount type=tmpfs,destination=/var/cache/nginx,tmpfs-size=16m.
Docker Compose: read_only and tmpfs
In Compose, the same setup is two keys on the service:
# compose.yaml
services:
web:
image: nginx:alpine
read_only: true
tmpfs:
- /var/cache/nginx:size=16m
- /run
ports:
- "8080:80"
docker compose up -d starts NGINX with a read-only root filesystem and two writable tmpfs mounts.
Kubernetes: securityContext.readOnlyRootFilesystem
In Kubernetes, you set readOnlyRootFilesystem: true in the container’s securityContext. It’s a per-container field, there is no pod-level equivalent. Instead of tmpfs mounts, you use emptyDir volumes for the writable paths. An emptyDir is created when the Pod is scheduled to a node and deleted with the Pod. By default it’s backed by the node’s disk; with medium: Memory it’s a tmpfs.
Here is the NGINX example from above as a Pod:
# pod.yaml
apiVersion: v1
kind: Pod
metadata:
name: webserver
spec:
containers:
- name: webserver
image: nginx:alpine
securityContext:
readOnlyRootFilesystem: true
ports:
- containerPort: 80
volumeMounts:
- name: nginx-cache
mountPath: /var/cache/nginx
- name: run
mountPath: /run
volumes:
- name: nginx-cache
emptyDir: {}
- name: run
emptyDir:
medium: Memory
sizeLimit: 1Mi
kubectl apply -f pod.yaml
kubectl port-forward pod/webserver 8080:80
Two things to keep in mind with medium: Memory: files in it count against the container’s memory limit, and they’re lost on a node reboot. Always set a sizeLimit so a runaway process can’t fill the node’s RAM. For caches that may grow, a disk-backed emptyDir (with a sizeLimit as well) is usually the better choice.
Read-only root filesystem and Pod Security Standards
PodSecurityPolicy, which used to be the way to enforce readOnlyRootFilesystem cluster-wide, was removed in Kubernetes 1.25. Its successor, Pod Security Admission, enforces the Pod Security Standards
. Note that the restricted profile does not require readOnlyRootFilesystem. It requires a non-root user, no privilege escalation, dropped capabilities and a seccomp profile, and it allows emptyDir volumes. If you want read-only root filesystems everywhere, enforce them with a policy engine like Kyverno, OPA Gatekeeper or a ValidatingAdmissionPolicy.
The official nginx image runs as root and binds port 80, so it won’t pass restricted. The nginxinc/nginx-unprivileged image runs as UID 101, listens on 8080 and writes everything (PID file and temp paths) to /tmp. That means a single emptyDir is enough:
# deployment.yaml
apiVersion: v1
kind: Namespace
metadata:
name: web
labels:
pod-security.kubernetes.io/enforce: restricted
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: webserver
namespace: web
spec:
replicas: 1
selector:
matchLabels:
app: webserver
template:
metadata:
labels:
app: webserver
spec:
securityContext:
runAsNonRoot: true
seccompProfile:
type: RuntimeDefault
containers:
- name: webserver
image: nginxinc/nginx-unprivileged:alpine
ports:
- containerPort: 8080
securityContext:
readOnlyRootFilesystem: true
allowPrivilegeEscalation: false
capabilities:
drop: ["ALL"]
resources:
limits:
memory: 128Mi
volumeMounts:
- name: tmp
mountPath: /tmp
volumes:
- name: tmp
emptyDir:
medium: Memory
sizeLimit: 32Mi
Without the /tmp volume, this container fails the same way as before (mkdir() "/tmp/proxy_temp" failed (30: Read-only file system)).
Finding the paths your app writes to
The fastest way I know is the one used above: start the container read-only, read the error, add a mount, repeat. For a more complete picture, run the container without --read-only, exercise it, and ask Docker what changed:
docker run -d --name probe nginx:alpine
docker diff probe
C /run
A /run/nginx.pid
C /var/cache/nginx
A /var/cache/nginx/client_temp
...
C /etc/nginx/conf.d/default.conf
There they are: /run, /var/cache/nginx, and the default.conf the entrypoint patched. Every A (added) or C (changed) path outside your volumes is a candidate for a tmpfs or emptyDir. Keep that list as short as possible, and prefer pointing the application at a single directory like /tmp over mounting half the filesystem writable.
Conclusion
A read-only root filesystem is a one-line change in Docker (--read-only), Compose (read_only: true) and Kubernetes (readOnlyRootFilesystem: true). The work is in finding the few paths your application has to write to and mounting a tmpfs or emptyDir there. Once that’s done, you get a container that can’t be modified at runtime, and that’s worth it for every workload you ship.