Why won't my pod start? SCC troubleshooting

Almost everyone onboarding to OpenShift hits one of two errors on their first real deployment. Both come back to Security Context Constraints. Here’s how to read and fix them.

Watch on YouTube ↗

Error 1 — the image wants to be root

container has runAsNonRoot and image will run as root

Cause: the container image was built to run as root (no USER directive, or USER 0), but restricted-v2 forbids it.

The durable fix is to rebuild the image to run as an arbitrary non-root user. In the Dockerfile, create a non-root user and — crucially — make the files group-owned and group-writable, because OpenShift assigns a random UID but a predictable fsGroup:

RUN chgrp -R 0 /app && chmod -R g=u /app
USER 1001

chmod -R g=u says “give the group the same permissions as the owner,” so whatever random UID OpenShift injects can still read and write, since it lands in group 0.

The temporary fix, only for legacy images you can’t rebuild yet, is to grant anyuid to that workload’s service account — scoped, justified, and time-boxed.

Error 2 — nothing will admit this pod

unable to validate against any security context constraint

Cause: the pod spec asks for something no SCC available to its service account permits — a hardcoded runAsUser outside the namespace’s allotted range, a privileged flag, extra capabilities, host mounts, and so on.

Fix: align the pod’s securityContext with restricted-v2 rather than demanding more. A clean, restricted-friendly spec looks like:

spec:
  securityContext:
    runAsNonRoot: true
    seccompProfile:
      type: RuntimeDefault
  containers:
    - name: app
      securityContext:
        allowPrivilegeEscalation: false
        capabilities:
          drop: ["ALL"]

Notice what’s absent: no explicit runAsUser. Let the SCC assign the UID from the namespace range rather than picking one yourself — hardcoding a UID is the single most common trigger for this error.

Tip

Helm charts that hardcode a UID (many older ones do) fail here. Good charts expose a switch to defer to OpenShift — for example Bitnami’s adaptSecurityContext, covered in the Postgres guide. The pattern is always the same: stop the chart from demanding a UID so the SCC can do its job.

A debugging checklist

# 1. What SCC (if any) did the pod get?
oc get pod <pod> -o jsonpath='{.metadata.annotations.openshift\.io/scc}'

# 2. What can this service account actually use?
oc adm policy who-can use scc restricted-v2

# 3. What UID range is the namespace handing out?
oc get ns <namespace> -o jsonpath='{.metadata.annotations.openshift\.io/sa\.scc\.uid-range}'

# 4. What did admission actually object to?
oc describe pod <pod> | sed -n '/Events/,$p'

Nine times out of ten the answer is: the image or the chart is asking for a UID it shouldn’t, and the fix lives in the manifest, not in a bigger SCC.