Introduction

In Kubernetes, securityContext is where you declare how a pod or container should run from a Linux security perspective. It is the place to say "run as non-root," "drop capabilities," "do not allow privilege escalation," and other hardening rules. The important detail is that Kubernetes lets you set some of these rules at the pod level and some at the individual container level.

Pod-Level Versus Container-Level securityContext

A pod-level securityContext lives under spec.securityContext and provides defaults for the whole pod. A container-level securityContext lives under spec.containers[].securityContext and applies only to that container.

Here is a deployment showing both:

1apiVersion: apps/v1
2kind: Deployment
3metadata:
4  name: web-app
5spec:
6  replicas: 1
7  selector:
8    matchLabels:
9      app: web-app
10  template:
11    metadata:
12      labels:
13        app: web-app
14    spec:
15      securityContext:
16        runAsNonRoot: true
17        runAsUser: 10001
18        runAsGroup: 10001
19        fsGroup: 20001
20      containers:
21        - name: app
22          image: nginx:1.27
23          ports:
24            - containerPort: 80
25          securityContext:
26            allowPrivilegeEscalation: false
27            readOnlyRootFilesystem: true
28            capabilities:
29              drop:
30                - ALL

This is a good baseline example for many workloads.

What the Common Fields Mean

These fields show up often in hardened deployments:

• 'runAsNonRoot: require the process to run as a non-root user'
• 'runAsUser: numeric user ID inside the container'
• 'runAsGroup: primary group ID'
• 'fsGroup: group ownership for mounted volumes'
• 'allowPrivilegeEscalation: block privilege escalation through mechanisms such as setuid'
• 'readOnlyRootFilesystem: make the container root filesystem read-only'
• 'capabilities.drop: remove Linux capabilities that the process does not need'

You do not need every field for every workload, but these are the most common secure defaults.

A Practical Pattern

For many web services, a good starting point is:

• run as non-root
• drop all capabilities
• disable privilege escalation
• make the root filesystem read-only if the app can tolerate it

That is exactly what the previous example does. It keeps the container closer to least privilege without requiring a very exotic setup.

When You Need Writable Paths

The moment you set readOnlyRootFilesystem: true, some applications fail because they expect writable directories such as /tmp, cache folders, or generated config paths.

The usual solution is to mount a writable volume only where needed:

1apiVersion: apps/v1
2kind: Deployment
3metadata:
4  name: api-app
5spec:
6  replicas: 1
7  selector:
8    matchLabels:
9      app: api-app
10  template:
11    metadata:
12      labels:
13        app: api-app
14    spec:
15      securityContext:
16        runAsNonRoot: true
17        runAsUser: 10001
18      containers:
19        - name: app
20          image: my-api:latest
21          securityContext:
22            allowPrivilegeEscalation: false
23            readOnlyRootFilesystem: true
24          volumeMounts:
25            - name: temp
26              mountPath: /tmp
27      volumes:
28        - name: temp
29          emptyDir: {}

This keeps the base filesystem locked down while still giving the application a safe writable area.

Pod Defaults and Per-Container Overrides

Pod-level settings are useful when all containers in the pod should share the same defaults. Container-level settings are better when one container needs something different.

For example, a sidecar might need a different capability set than the main app container. In that case, keep the shared defaults at the pod level and override only the exception.

This is cleaner than duplicating the full security configuration on every container entry.

Verify the Image Supports Your Settings

A secure Kubernetes manifest still fails if the container image itself expects to run as root or write to protected filesystem paths. Hardening is a contract between the deployment spec and the image design.

Before enabling strict settings, check:

• which user the image expects
• whether startup scripts need root
• which directories must be writable
• whether the app binds to privileged ports

A service listening on port 80, for example, may need extra image or runtime design decisions if you want it to run cleanly as a non-root user.

Common Pitfalls

One common mistake is setting runAsNonRoot: true while the image still defaults to root and has no valid non-root user configured. The pod then fails at startup.

Another issue is enabling readOnlyRootFilesystem: true without providing writable mounts for temp files, logs, or caches the application still expects.

Developers also sometimes put every field at the container level even when the whole pod should share the same defaults. That creates duplication and makes policy harder to maintain.

Finally, dropping all capabilities is a good default, but some workloads genuinely need a specific capability back. Harden first, then add back only what the application proves it needs.

Summary

• 'securityContext can be configured at both pod and container scope.'
• A strong baseline is non-root execution, no privilege escalation, and dropped capabilities.
• 'readOnlyRootFilesystem improves hardening but often requires explicit writable mounts such as /tmp.'
• Pod-level defaults reduce duplication, while container-level settings handle exceptions.
• Secure settings must match the expectations of the container image or the workload will fail to start.