fix(kubernetes): shorten the HCL workspace and add an OIDC example - #14427

For Kubernetes users: examples/kubernetes/hosted-nvidia.tf now applies with its default workspace, the Kubernetes guide lists the NetworkPolicy enforcement that OpenShell requires, and the new examples/kubernetes/managed-oidc.yaml is a complete document for a managed gateway with the oidc profile and a registry pull Secret.

Problem

• hosted-nvidia.tf, which examples/gtc-dc/kubernetes-amd64.tf links to, defaults workspace to gtc-dc-kubernetes-cloud, 23 characters. The pinned OpenShell refuses a workspace name over 19 characters (MAX_ROUTABLE_NAME_LEN), and only when apply creates the workspace, after the gateway is installed. The run recorded on feat(examples): manage GTC DC Kubernetes gateways #14315 hit this. The HCL plan scenario passed, because plan doesn't create the workspace.
• The guide's prerequisites didn't say that OpenShell requires a network plugin that enforces NetworkPolicy. OpenShell's NetworkPolicies are what keep a sandbox's workload pod off the network. Kubernetes accepts them without such a plugin, so nothing reports one that's missing.
• No example used the oidc profile on its own, or imagePullSecrets. The only OIDC example, gpu-autoscaling/two-runtimes.yaml, depends on the GPU chart. The guide also didn't say:
  • that the gateway token needs the admin role;
  • how to create the caConfigMap;
  • how the OpenShell CLI signs in where no browser can open;
  • which role lets the CLI reach the deployment's workspace.

Change

• hosted-nvidia.tf:
  • Default workspace to gtc-dc-k8s-cloud.
  • Add a validation block with OpenShell's name rule: at most 19 characters, a DNS label, and no --.
  • gtc-dc-kubernetes-amd64-hcl.tftest.hcl plans the old default and expects that validation to fail.
  • examples/gtc-dc/README.md states the limit.
• Prerequisites (kubernetes.md): add a network plugin that enforces ingress and egress NetworkPolicy, linked to OpenShell's requirement. Say that nothing reports a plugin that ignores NetworkPolicy. Add it to the threat model's "Relies on" column.
• examples/kubernetes/managed-oidc.yaml:
  • An OpenClaw and a Hermes agent on the isolated network tier, sharing hosted NVIDIA inference.
  • The oidc profile with caConfigMap and a token, and imagePullSecrets.
  • The OIDC and registry sections of the guide link it.
• OIDC section:
  • Add the kubectl create configmap command for caConfigMap.
  • The token needs the role admin_role names; without it, plan fails with observation permission denied.
  • When scopes_claim is set, the token also needs the same scopes as an external gateway's token.
• "Reach the Gateway from the OpenShell CLI":
  • Add the client-credentials sign-in (OPENSHELL_OIDC_CLIENT_SECRET), with openshell gateway login to sign in again, because the pinned CLI doesn't renew that token (bug(cli): client-credentials gateway login stops working when the access token expires OpenShell#4287).
  • Cite feat(examples): add a Fabric load client for GPU autoscaling runs #14192's kind run of it beside Update the OpenShift docs with the bare-metal run's results #14131.
  • A token with the role admin_role names reaches the deployment's workspace. A token with only the role user_role names needs a platform admin to add its subject to the workspace first, and with only that role openshell status reports authorization denied.

Left out:

• An OpenShift copy of the OIDC example, because [OpenShift] Let the OpenShell chart leave the gateway's UID to OpenShift #13828 plans to fold the OpenShift examples into the Kubernetes ones.
• Agent interfaces in the example, which no run here checked.
• A managed-oidc.yaml row in examples/kubernetes/README.md, which docs(examples): add Kubernetes placement and NodePort examples with an index #14428 adds; whichever of the two merges second adds the row.
• Correcting the guide where it says the gateway requires its client certificate. The pinned gateway asks for one but doesn't require it: in the run below, a call with only an OIDC token succeeded, and the CLI worked with only the gateway's CA in its mtls directory. That fix touches text outside this change.

Beyond CI

• managed-oidc.yaml on k3s: applied on single-node k3s v1.37.1+k3s1 with Agent Sandbox 1.0.3, the local-path StorageClass, and k3s's NetworkPolicy controller.
  • Setup:
    • Images built from c5bf74d and pushed to a loopback registry.
    • Hosted NVIDIA inference.
    • The e2e test issuer in another namespace, with its CA in the issuer-ca ConfigMap.
    • The example with only its UID, context, namespace, issuer settings and image digests changed.
  • Results:
    • Plan and apply succeeded, and both agents replied through the gateway.
    • registry-credentials was on the gateway, supervisor and sandbox pods.
    • A second plan found no changes.
    • Destroy succeeded and kept the namespace, the gateway's volume and its Secrets.
• Token without the admin role: on the same deployment, a token re-signed with only the user role made plan fail with observation permission denied.
• hosted-nvidia.tf on k3s, with its new default workspace: the same cluster and images, with OpenTofu and the providers from a bundle built at c5bf74d.
  • Setup: the two claims prepared and labelled as examples/gtc-dc/README.md says. Only the provider versions, UID, context, namespace and images were set; workspace kept its default.
  • Init, validate, plan and apply succeeded, and OpenShell created the workspace gtc-dc-k8s-cloud.
  • OpenClaw and Hermes each replied READY through fabric-agent-ctl invoke, and each had its claim's workspace/ and artifacts/ mounted and writable.
  • A second plan found no changes.
  • The README's targeted destroy removed the gateway and both agents, and kept the storage resource and both claims.
• OpenShell CLI sign-in on a three-node cluster: k3d v5.9.0 with k3s v1.37.1+k3s1 and Agent Sandbox 1.0.3, with Keycloak 26.4 in the cluster as the issuer and three confidential clients. The gateway was docs(examples): add Kubernetes placement and NodePort examples with an index #14428's published-nodeport.yaml, which uses the same oidc profile; NemoClaw's own token came from one of the clients.
  • The guide's steps with the pinned CLI 0.1.7: the client certificate copied from <release>-client-tls, SSL_CERT_FILE set to the issuer's CA, then openshell gateway add with OPENSHELL_OIDC_CLIENT_SECRET. The CLI printed Authenticated via client credentials, and openshell status reported Connected and Authenticated (OIDC).
  • This worked both through the port forward to the gateway pod and at the published endpoint.
  • With the admin role, openshell sandbox list listed the agent, and openshell sandbox exec … fabric-agent-ctl invoke got READY.
  • With only the user role, openshell status reported Authenticated (OIDC; authorization denied), and sandbox commands failed with not a member of workspace. After openshell workspace member add … --role user, the same client listed and invoked the agent, and a NemoClaw plan still found no changes.
• Not run:
  • The browser sign-in: no browser here. Update the OpenShift docs with the bare-metal run's results #14131 records one.
  • A cluster whose network plugin doesn't enforce NetworkPolicy.

🤖 Generated with Claude Code