Skip to content

docs(openshift): add JWT secret creation step before chart install #2089

Closed

Description

@ChristianZaccaria

Problem Statement

The OpenShift install guide instructs users to disable pkiInitJob but only mentions the need to pre-create the sandbox JWT signing Secret as an afterthought note below the helm install command. Every user hits a MountVolume.SetUp failure for the openshell-jwt-keys Secret on first install and has to manually create the Secret and restart the pod.

Reference: https://github.com/NVIDIA/OpenShell/blob/main/docs/kubernetes/openshift.mdx?plain=1#L61-L63

Resolution

The pkiInitJob certgen Job works on OpenShift without being disabled — its security context is compatible with the restricted SCC. The original guidance to disable it was stale.

Changes span three files:

  • docs/kubernetes/openshift.mdx — removed pkiInitJob.enabled=false override, removed manual JWT secret creation step, updated disableTls table row description
  • deploy/helm/openshell/README.md.gotmpl — matching quick-start snippet cleanup, fixed OpenShift install guide link
  • deploy/helm/openshell/README.md — regenerated via mise run helm:docs

Agent Investigation

Traced the secret requirements through the codebase:

  • Secret name: openshell-jwt-keys (from openshell.sandboxJwtSecretName helper in _helpers.tpl)
  • Secret keys: signing.pem, public.pem, kid (from jwt_signing_secret() in certgen.rs)
  • Key type: Ed25519 PKCS#8/SPKI PEM (from PkiBundle struct in openshell-bootstrap/src/pki.rs)
  • Kid format: 16 bytes hex-encoded (from test assertion in pki.rs)
  • Certgen Job security context: allowPrivilegeEscalation: false, capabilities.drop: [ALL], no hardcoded runAsUser or fsGroup — compatible with OpenShift's restricted SCC

Activity

  1. TaylorMutch commented on Jul 1, 2026

    @TaylorMutch
    Collaborator

    The instructions may be out of date to say to pre-create the secret. We had an issue before but added the generate-certs option to the gateway which the init job uses now.

    It would be great to validate whether the step is needed or if we can drop that from the docs and allow normal pki init to work on openshift.

  2. ChristianZaccaria commented on Jul 2, 2026

    @ChristianZaccaria
    ContributorAuthor

    Thanks @TaylorMutch. I've tested this out by deploying OpenShell via Helm without the server.disableTls value. I can confirm that the certgen Job runs fine under OpenShift's restricted SCC, and the OpenShell Gateway pod started successfully. No need to disable pkiInitJob anymore.

    I've updated this GitHub issue to reflect the new findings and the documentation updates required. - I'm ready to make a PR if this all sounds good.

  3. TaylorMutch commented on Jul 2, 2026

    @TaylorMutch
    Collaborator

    Sounds good!

  4. removed
    state:triage-neededOpened without agent diagnostics and needs triage
    on Oct 1, 2026
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

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions