Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 37 ยท Security and Operators

Security Context Constraints (SCC) in OpenShift

Learn why OpenShift runs containers as random non-root users, how restricted-v2, anyuid and privileged SCCs work, and how to fix permission denied errors safely.

The first time many people deploy an image from Docker Hub to OpenShift, it fails with permission denied or refuses to start. The reason is Security Context Constraints (SCCs). An SCC is an OpenShift policy object that decides what a pod may do: which user ID it runs as, whether it can be privileged, which volume types it can mount, and which Linux capabilities it receives.

Kubernetes has Pod Security Admission for similar goals. SCCs are older, finer grained and enforced by default on OpenShift, so you must understand them to run real images.

No cluster runs on this page. The YAML and oc commands are read-only. The runnable Python stand-ins model how an SCC decision is made so you can experiment with the logic.

What the default SCC does

New pods get the restricted-v2 SCC unless a more permissive one is granted. It enforces:

  • The container does not run as root (UID 0).
  • The UID is taken from a range assigned to the project, for example 1000680000, not the one in the image.
  • The primary group is 0 (root group) so files can be shared, but the user itself has no special rights.
  • All Linux capabilities are dropped, privilege escalation is disallowed, and seccomp is on (RuntimeDefault).
  • Only safe volume types are allowed (configMap, secret, emptyDir, PVC and similar).

See the range of your project:

Terminal
oc get project shop -o jsonpath='{.metadata.annotations}'
# openshift.io/sa.scc.uid-range: 1000680000/10000

Because the UID is random, an image that writes to a directory owned by appuser fails. The fix is to make those directories group-writable by group 0, which every OpenShift UID belongs to:

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

Use a numeric USER and listen on a port above 1024 (for example 8080), since non-root users cannot bind to port 80.

Common SCCs

SCC Lets pods Use for
restricted-v2 Run as a random non-root UID Almost everything
nonroot-v2 Pick any non-root UID Images with a fixed non-root user
anyuid Run as any UID, including root Legacy images that need UID 0
hostnetwork, hostaccess Use host network or paths Node-level agents
privileged Do anything Only trusted cluster components

List them and see who may use one:

Terminal
oc get scc
oc describe scc anyuid
oc adm policy who-can use scc anyuid

How a pod is matched to an SCC

When a pod is created, the admission controller collects the SCCs that the creating user and the pod's service account are allowed to use (through RBAC use permission on the SCC). It sorts them by priority and restrictiveness and picks the first one that can admit the pod. If none can, the pod is rejected with an error such as:

TEXT
unable to validate against any security context constraint:
[provider "restricted-v2": .spec.containers[0].securityContext.runAsUser: Invalid value: 0 ...]
Python Stand-in: SCC admission check

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Granting an SCC (carefully)

You grant access to a service account, never to a human user, and only to the project that needs it:

Terminal
oc create serviceaccount legacy-app
oc adm policy add-scc-to-user anyuid -z legacy-app -n shop
oc set serviceaccount deployment/legacy-app legacy-app

add-scc-to-user ... -z NAME adds the RBAC use permission for the named service account in the current namespace. The pod then needs to be recreated with oc rollout restart so admission runs again.

Prefer fixing the image over granting anyuid. Granting a permissive SCC means every pod using that service account may run as root, so treat it as a security exception that needs review. Never grant privileged for application workloads.

Reading the SCC that was applied

Terminal
oc get pod shop-api-1-abcde -o jsonpath='{.metadata.annotations.openshift\.io/scc}'

Pods carry this annotation, which answers "why did this pod run as root?" at once. In a stand-in, we can scan a list of pod annotations the same way an audit script would.

Python Stand-in: audit SCC annotations

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Troubleshooting checklist

  1. oc get events and read the FailedCreate message for the SCC error.
  2. oc get pod -o yaml | grep scc to see what actually applied.
  3. Check the image's USER and any directories it writes to.
  4. Use oc adm policy scc-subject-review -f pod.yaml to see which SCC would admit a pod definition.
  5. Last resort, grant anyuid to a dedicated service account in that project only.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the default restricted-v2 SCC do about the user ID?

    OpenShift picks a UID from the project's annotated range so containers do not run as root.
  2. 2. An image fails writing to /data owned by its own user. Best fix?

    OpenShift UIDs belong to group 0, so chgrp 0 and g=u give access without extra privileges.
  3. 3. Who should receive an SCC grant such as anyuid?

    Grant the narrowest subject needed, usually one service account in one project.
  4. 4. Which annotation on a pod shows the SCC that admitted it?

    The openshift.io/scc annotation records the matched constraint.

Summary

  • SCCs control UID, privileges, capabilities and volumes for pods.
  • restricted-v2 is the default: non-root, random UID, no capabilities.
  • Make images arbitrary-UID friendly: numeric USER, group-0 writable paths, ports above 1024.
  • Grant permissive SCCs to dedicated service accounts only, and rarely.
  • Read the openshift.io/scc annotation when debugging.

Next: RBAC: roles and bindings