Skip to content

Kubernetes Setup: Document and validate SupplementalGroupsPolicy requirements #5772

Open

Description

@enzv

User Story

I use OpenShell to run sandboxed agents on a local Kubernetes cluster.

During a CNCF ChatLoopBackOff livestream with @drew, I deployed OpenShell v0.1.9 on Minikube following the official Kubernetes setup guide.

The gateway started successfully, but sandbox creation failed because the node did not support SupplementalGroupsPolicy: Strict.

Problem Statement

The v0.1.9 Kubernetes setup guide lists Kubernetes 1.29+ as a prerequisite but does not mention the container runtime requirements for SupplementalGroupsPolicy: Strict.

Sandbox Pods fail with:

SupplementalGroupsPolicyNotSupported
Pod was rejected: SupplementalGroupsPolicy=Strict is not supported in this node

Impact / Why This Matters

Users can successfully deploy the gateway following the documented prerequisites but still be unable to create sandboxes.

The incompatibility is discovered only after attempting to start a sandbox, making it difficult to identify the missing runtime capability.

Proposed Design

Update the Kubernetes setup guide's Prerequisites section to document the requirements for SupplementalGroupsPolicy: Strict.

According to the official Kubernetes documentation:

  • containerd 2.0+ and CRI-O 1.31+ support this feature.
  • Starting with Kubernetes 1.33, Pods requesting Strict are rejected when the node lacks support.
  • Node compatibility can be verified through .status.features.supplementalGroupsPolicy.

Include a verification command:

kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.nodeInfo.containerRuntimeVersion}{"\t"}{.status.features.supplementalGroupsPolicy}{"\n"}{end}'

The guide should explain the SupplementalGroupsPolicyNotSupported error and direct users to a compatible runtime without weakening sandbox isolation.

Acceptance Criteria

  • Kubernetes setup documentation specifies the runtime requirements for SupplementalGroupsPolicy: Strict.
  • Documentation includes a command to verify node support.
  • Users receive clear guidance when their cluster does not support the required policy.
  • The existing sandbox security guarantees are preserved.

Alternatives Considered

Users can inspect Kubernetes events and consult the upstream Kubernetes documentation to diagnose the failure.

However, this requires troubleshooting a failed sandbox rather than identifying the incompatibility during setup.

Agent Investigation

Reviewed docs/kubernetes/setup.mdx at tag v0.1.9.

The prerequisites cover Kubernetes version, RBAC, NetworkPolicy enforcement, Helm, and Agent Sandbox, but do not mention SupplementalGroupsPolicy or its runtime compatibility requirements.

Checklist

  • I've reviewed existing issues and the published docs
  • This is a design proposal, not a "please build this" request
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    state:triage-neededOpened without agent diagnostics and needs triage

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions