Kubernetes v1.35: Fine-grained Supplemental Groups Control Graduates to GA

Source: Kubernetes Blog

Graduation Announcement

On behalf of Kubernetes SIG Node, we are pleased to announce the graduation of fine‑grained supplemental groups control to General Availability (GA) in Kubernetes v1.35!

• The new pod field supplementalGroupsPolicy was introduced as an opt‑in alpha feature in v1.31, graduated to beta in v1.33, and is now GA.
• This feature gives you precise control over supplemental groups in Linux containers, strengthening security—especially when accessing volumes.
• It also improves the transparency of UID/GID details inside containers, offering better security oversight.

Upgrade note – If you are upgrading from v1.32 or earlier, be aware of a behavioral breaking change introduced since the beta (v1.33). See the behavioral changes and upgrade considerations sections of the previous blog for details.

---

Motivation: Implicit group memberships defined in /etc/group

Even though many cluster admins/users may not notice it, Kubernetes merges group information from the pod with the /etc/group file inside the container image by default.

Example manifest

apiVersion: v1
kind: Pod
metadata:
  name: implicit-groups-example
spec:
  securityContext:
    runAsUser: 1000          # UID
    runAsGroup: 3000         # primary GID
    supplementalGroups: [4000]
  containers:
  - name: example-container
    image: registry.k8s.io/e2e-test-images/agnhost:2.45
    command: ["sh", "-c", "sleep 1h"]
    securityContext:
      allowPrivilegeEscalation: false

What does id show inside the container?

uid=1000 gid=3000 groups=3000,4000,50000

The 50000 GID appears even though it isn’t defined in the pod manifest.

It comes from the /etc/group file in the container image:

user-defined-in-image:x:1000:
group-defined-in-image:x:50000:user-defined-in-image

The primary user (UID 1000) belongs to group 50000, so Kubernetes implicitly merges that group into the container’s supplemental groups.

Why is this a problem?

• The implicit GIDs are invisible to policy engines because they don’t appear in the pod spec.
• This can cause unexpected access‑control issues, especially when accessing volumes (see kubernetes/kubernetes#112879).

---

Fine‑grained supplemental groups control – supplementalGroupsPolicy

A pod’s .spec.securityContext now includes the field supplementalGroupsPolicy. It determines how Kubernetes calculates the supplemental groups for container processes.

Strict policy example

apiVersion: v1
kind: Pod
metadata:
  name: strict-supplementalgroups-policy-example
spec:
  securityContext:
    runAsUser: 1000
    runAsGroup: 3000
    supplementalGroups: [4000]
    supplementalGroupsPolicy: Strict
  containers:
  - name: example-container
    image: registry.k8s.io/e2e-test-images/agnhost:2.45
    command: ["sh", "-c", "sleep 1h"]
    securityContext:
      allowPrivilegeEscalation: false

Running id inside the container now yields:

uid=1000 gid=3000 groups=3000,4000

The unwanted group 50000 is no longer present.

Enforcing supplementalGroupsPolicy: Strict (e.g., via a policy engine) prevents implicit supplemental groups from being added to a pod.

Note: A container with sufficient privileges can still change its process identity after start‑up. The supplementalGroupsPolicy only affects the initial process identity.

---

Exposing the attached process identity in Pod status

The feature also adds the initial process identity to the pod status:

status:
  containerStatuses:
  - name: ctr
    user:
      linux:
        uid: 1000
        gid: 3000
        supplementalGroups:
        - 3000
        - 4000

Important: The values in status.containerStatuses[].user.linux reflect the first attached identity. If a container can call setuid(2), setgid(2), setgroups(2), etc., it can later modify its identity, making the actual runtime identity dynamic.

Mitigating privilege escalation

To limit a container’s ability to change its identity, consider the following simple mitigations:

1. Set privilege: false and allowPrivilegeEscalation: false in the container’s securityContext.
2. Conform your pod to the Restricted policy in Pod Security Standards.

---

TL;DR

• supplementalGroupsPolicy (GA in v1.35) lets you choose between the historic Merge behavior and a Strict mode that eliminates hidden group memberships.
• Use Strict (or enforce it via policy) to avoid security surprises caused by implicit groups from /etc/group.
• The initial identity is now visible in pod status, helping you audit and verify group assignments.

---

Overview

• The kubelet does not have visibility into NRI plugins or the internal workings of the container runtime.
• A cluster administrator (or a highly‑privileged workload with local‑admin permissions) can change supplemental groups for any pod.
• This is outside the scope of Kubernetes control and should not be a concern for security‑hardened nodes.

---

Strict Policy Requires Up‑to‑Date Container Runtimes

The high‑level container runtime (e.g., containerd, CRI‑O) is responsible for calculating the supplemental group IDs that will be attached to containers. Therefore, supplementalGroupsPolicy: Strict requires a CRI runtime that supports this feature.

• The older behavior (supplementalGroupsPolicy: Merge) works with runtimes that do not support the feature, because it is fully backward‑compatible.

Supported CRI Runtimes

---

Verifying Feature Support

You can check whether the feature is enabled on a node via the status.features.supplementalGroupsPolicy field (different from status.declaredFeatures introduced in KEP‑5328: Node Declared Features).

apiVersion: v1
kind: Node
...
status:
  features:
    supplementalGroupsPolicy: true

---

Best Practices

• As container runtimes adopt this feature universally, many security policies will start enforcing the Strict behavior for stronger security.
• Ensure your Pods are ready for this enforcement by declaring all supplemental groups explicitly in the Pod spec, rather than relying on defaults baked into images.

---

Getting Involved

This enhancement was driven by the SIG Node community.
Join the discussion, share ideas, and provide feedback on this feature and related topics. The community looks forward to hearing from you!

---

Learn More

• Configure a Security Context for a Pod or Container – detailed guidance on supplementalGroupsPolicy.
• KEP‑3619 – Fine‑grained SupplementalGroups control.