fix(drivers): require admission labels for external resources

[drew]

Summary

Require external resources attached to sandboxes to carry explicit operator-controlled admission labels. This creates a consistent application-level boundary across compute drivers while still allowing operators to customize or disable the policy when needed.

Caller-provided driver config is also disabled by default and requires an explicit gateway opt-in.

Changes

• Add a shared resource_admission configuration with these defaults:
  • openshell.ai/sandbox-attachable = "true"
  • openshell.ai/sandbox-attachable-workspace = "${workspace}"
• Disable caller-provided driver config by default with allow_driver_config = false.
• Require admission labels for Kubernetes PVCs, Secrets, ConfigMaps, RuntimeClasses, PriorityClasses, and image-pull Secrets.
• Apply workspace labels to data-bearing resources while allowing shared infrastructure to use the fixed approval label.
• Evaluate Kubernetes resources from the OpenShell-owned Pod template rather than the mutated live Pod.
• Admit managed-workspace image-pull Secrets at their source before copying them with gateway ownership metadata.
• Require labels on Docker and Podman named volumes.
• Reject external host resources that do not have a trusted label resolver while admission is enabled.
• Revalidate admitted resource identities during sandbox lifecycle operations.
• Keep GPU device attachments exempt from label admission for now.
• Document configuration, migration behavior, and driver-specific examples.

Example Kubernetes resource:

metadata:
  labels:
    openshell.ai/sandbox-attachable: "true"
    openshell.ai/sandbox-attachable-workspace: "team-a"

Example Docker volume:

docker volume create \
  --label openshell.ai/sandbox-attachable=true \
  --label openshell.ai/sandbox-attachable-workspace=team-a \
  team-a-data

Example Podman volume:

podman volume create \
  --label openshell.ai/sandbox-attachable=true \
  --label openshell.ai/sandbox-attachable-workspace=team-a \
  team-a-data

Gateway configuration

Admission is enabled by default. The default Kubernetes configuration is equivalent to:

[openshell.drivers.kubernetes]
allow_driver_config = false

[openshell.drivers.kubernetes.resource_admission]
enabled = true

[openshell.drivers.kubernetes.resource_admission.required_labels]
"openshell.ai/sandbox-attachable" = "true"
"openshell.ai/sandbox-attachable-workspace" = "${workspace}"

The same configuration shape is available for Docker, Podman, VM, and MXC drivers by replacing kubernetes with the configured driver name.

To customize the required labels:

[openshell.drivers.kubernetes.resource_admission.required_labels]
"platform.example.com/sandbox-attachable" = "approved"
"platform.example.com/workspace" = "${workspace}"

To explicitly permit caller-provided driver config:

[openshell.drivers.kubernetes]
allow_driver_config = true

Admission can be disabled explicitly for deployments that authorize external resources elsewhere:

[openshell.drivers.kubernetes.resource_admission]
enabled = false

Testing

• mise run pre-commit passes
• Core, Kubernetes, Docker, and Podman unit tests pass
• Server admission and remote-driver handshake tests pass
• E2E tests added/updated (not run)

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-3538.docs.buildwithfern.com/openshell

[drew]

gator-agent

PR Review Status

The initial review found one blocking configuration-compatibility defect in the Kubernetes image-pull Secret path. The rest of the reviewed patch has no additional blocking findings.

Action required: prevent configured admission labels from colliding silently with OpenShell ownership labels, and add the regression test described inline.

Blocking findings:

• GATOR-661321ad-01: copied image-pull Secrets can overwrite a configured required label and make managed-workspace provisioning fail.

Carried findings:

• None

Non-blocking suggestions:

• None

Gator metadata

• Validation: Project-valid security hardening authored by a repository administrator with a detailed operator workflow and migration behavior.
• Docs: Fern documentation is updated for the new gateway configuration and driver behavior.
• Checks: Current branch, Helm, Trivy, and DCO checks are green; required runtime suites have not been dispatched.
• E2E: test:e2e, test:e2e-kubernetes, and test:windows will be required after review feedback is resolved.
• Head SHA: 661321adb75a576f6dc82a310b26283ca6ff2b13
• Base SHA: 99ed6a9df09a70981accfd39fe234fa1a648a93c
• Merge base SHA: 99ed6a9df09a70981accfd39fe234fa1a648a93c
• Patch ID: 709e2f4ab3b63510db17a0a2be4ccb9f1d7d113b
• Gator payload: 10
• Review mode: initial
• Previous reviewed SHA: none
• Review budget exhausted: no
• Maintainer decision required: no
• Next state: gator:in-review

[drew]

gator-agent

Blocked

Gator is blocked because PR #3538 conflicts with the current main branch, so the latest author delta and the existing review finding cannot be reconciled reliably.

Next action: @drew, merge or rebase the current main branch into this PR and resolve the conflicts. Gator will then review the author-only delta and re-check GATOR-661321ad-01.

Gator metadata

• Head SHA: 289894224d821d9d22588a5f6aa9aba36509fbc1
• Gator payload: 10
• Next state: gator:blocked
• Blocked reason: merge_conflict

[github-actions]

Label test:e2e applied for 1c5b4ed. Open the existing run and click Re-run all jobs to execute with the label set. The run will execute the standard E2E suite after building the required gateway, sandbox, and supervisor images once. The matching required CI gate status on this PR will flip green automatically once the run finishes.

[github-actions]

Label test:e2e-kubernetes applied for 1c5b4ed. Open the existing run and click Re-run all jobs to execute with the label set. The run will execute Kubernetes HA and credential-driver E2E after building the required gateway, sandbox, and supervisor images once. This is an optional proof-of-life suite; failures are visible in the workflow run but do not publish a required CI gate status.

[drew]

gator-agent

PR Review Status

Thanks @drew. I checked the rebased author-only delta and the reserved-label validation you added. The update rejects all three driver-owned label keys during configuration startup, covers that rejection, documents the reservation, and resolves GATOR-661321ad-01; no blocking findings remain.

Blocking findings:

• No blocking findings remain

Carried findings:

• None

Gator metadata

• Validation: Project-valid security hardening authored by a repository maintainer with a detailed operator workflow and migration behavior.
• Docs: Fern documentation is updated for the gateway configuration and driver behavior.
• Checks: Current-head branch checks are running; required runtime workflow dispatch is not yet confirmed.
• E2E: test:e2e, test:e2e-kubernetes, and test:windows are applied; dispatch must be confirmed before pipeline watch.
• Head SHA: 1c5b4ed5f2db1f804261d12c50203caae7a104a7
• Base SHA: f8b1fd8b57d353796e0a8cfae6131b201427d0db
• Merge base SHA: f8b1fd8b57d353796e0a8cfae6131b201427d0db
• Patch ID: b111aecf018f7aedc5bee9a103dad68986e023d8
• Gator payload: 10
• Review mode: follow_up
• Previous reviewed SHA: 661321adb75a576f6dc82a310b26283ca6ff2b13
• Review budget exhausted: no
• Maintainer decision required: no
• Next state: gator:in-review

[drew]

gator-agent

PR Review Status

Thanks @drew. I checked the new failure-context and VM idempotency delta. The clearer diagnostics are useful, but the Kubernetes 403 classification introduces one blocking lifecycle regression: a temporary or incomplete gateway RBAC state can now suspend a running sandbox even though its admitted resource identity and labels have not changed.

Action required: keep Kubernetes metadata-read authorization failures non-definitive during revalidation and add the regression coverage described inline.

Blocking findings:

• GATOR-e9a21c33-01: Kubernetes 403 metadata reads can suspend valid running sandboxes.

Carried findings:

• None

Gator metadata

• Validation: Project-valid security hardening authored by a repository maintainer with a detailed operator workflow and migration behavior.
• Docs: Fern documentation remains updated; this follow-up delta does not change the published configuration contract.
• Checks: Current-head branch, Windows, Helm, Trivy, and DCO checks are running or green; required runtime suites are not confirmed dispatched for this head.
• E2E: test:e2e, test:e2e-kubernetes, and test:windows are applied; runtime dispatch must wait until review feedback is resolved.
• Head SHA: e9a21c33e0256f06f47ee0d8090e44644f1e1ee9
• Base SHA: f8b1fd8b57d353796e0a8cfae6131b201427d0db
• Merge base SHA: f8b1fd8b57d353796e0a8cfae6131b201427d0db
• Patch ID: ff7a2a66cff8b20df1fc4301310b930dd213da75
• Gator payload: 10
• Review mode: follow_up
• Previous reviewed SHA: 1c5b4ed5f2db1f804261d12c50203caae7a104a7
• Review budget exhausted: no
• Maintainer decision required: no
• Next state: gator:in-review

[drew]

gator-agent

PR Review Status

Thanks @drew. I checked the latest author-only delta in critical-only mode. The update keeps Kubernetes 403 metadata lookups non-definitive and adds a reconciliation regression proving they do not suspend the sandbox, so GATOR-e9a21c33-01 is resolved; no new Critical findings were found.

Blocking findings:

• No blocking findings remain

Carried findings:

• None

Gator metadata

• Validation: Project-valid security hardening authored by a repository maintainer with a detailed operator workflow and migration behavior.
• Docs: Fern documentation remains updated for the gateway configuration and driver behavior.
• Checks: Current-head Branch Checks, Windows MSVC, Helm, Trivy, and runtime workflows are queued, running, or green.
• E2E: test:e2e, test:e2e-kubernetes, and test:windows are applied; current-head Branch E2E Checks and both Windows jobs are dispatched.
• Head SHA: 62a34a39ce8b4fdc382815866951897326b8f538
• Base SHA: f8b1fd8b57d353796e0a8cfae6131b201427d0db
• Merge base SHA: f8b1fd8b57d353796e0a8cfae6131b201427d0db
• Patch ID: 58227fd431c05fd194bef29008acf16583493f60
• Gator payload: 10
• Review mode: critical_only
• Previous reviewed SHA: e9a21c33e0256f06f47ee0d8090e44644f1e1ee9
• Review budget exhausted: yes
• Maintainer decision required: no
• Next state: gator:watch-pipeline

[drew]

gator-agent

PR Review Status

Thanks @drew. I reviewed the latest author-only E2E configuration delta in critical-only mode. It preserves admission defaults for in-process drivers while omitting those in-process settings for external drivers; no new Critical findings were found, and the two earlier Gator findings remain resolved.

Action required: a maintainer must re-run all jobs for the current-head Windows MSVC workflow so both x64 and ARM64 jobs execute with test:windows applied.

Blocking findings:

• No blocking code findings remain

Carried findings:

• None

Gator metadata

• Validation: Project-valid security hardening authored by a repository maintainer with a detailed operator workflow and migration behavior.
• Docs: Fern documentation remains updated; this E2E-only delta does not change the published configuration contract.
• Checks: Branch Checks, Helm, Trivy, and DCO are green; Branch E2E Checks are running, while the current Windows architecture jobs were skipped before test:windows was applied.
• E2E: test:e2e, test:e2e-kubernetes, and test:windows are applied; Windows dispatch still requires a maintainer rerun.
• Head SHA: 0c6c60c1eb70b1c4bc8e8a4f6e06d74ea09069bc
• Base SHA: f8b1fd8b57d353796e0a8cfae6131b201427d0db
• Merge base SHA: f8b1fd8b57d353796e0a8cfae6131b201427d0db
• Patch ID: 1647278189ab260d7c35eccaa21b6d8bd40e4d9f
• Gator payload: 10
• Review mode: critical_only
• Previous reviewed SHA: 62a34a39ce8b4fdc382815866951897326b8f538
• Review budget exhausted: yes
• Maintainer decision required: no
• Next state: gator:blocked
• Blocked reason: test_dispatch_required

[purp]

All issues addressed. LGTM. 🚢

[drew]

gator-agent

Monitoring Complete

Monitoring is complete because this PR has merged.

Final status: the PR merged after its required checks completed and maintainer approval was present. The remaining gator:blocked label is stale terminal-state cleanup.

I removed the active gator:* label because there is nothing left for gator to monitor on this PR.

Gator metadata

• Head SHA: 0c6c60c1eb70b1c4bc8e8a4f6e06d74ea09069bc
• Gator payload: 10