Skip to content
OpenShell
You are viewing OpenShell 0.1.7. The latest version is 0.1.9. Go to the latest version.

Managing Certificates

Configure the OpenShell Helm chart to use cert-manager for mTLS certificate issuance and automatic renewal.

The OpenShell gateway uses TLS for transport to sandbox supervisors. Supervisor Pods receive the gateway CA, not a client certificate or private key, and authenticate RPCs with sandbox JWTs. The generated client certificate can authenticate user clients when gateway mTLS user authentication is enabled; shared deployments can instead configure OIDC or a trusted access proxy. The Helm chart supports two ways to provision and manage the certificate bundle:

Mode When to use
Built-in pkiInitJob (default) The default path. A pre-install Kubernetes Job generates a self-signed CA and certificates during installation. No additional dependencies.
cert-manager Production deployments that need automatic certificate rotation managed by a running controller.

The rest of this page covers switching to cert-manager. The built-in mode requires no configuration.

Install cert-manager from the OCI registry with CRD support enabled:

Terminal window
helm upgrade --install cert-manager oci://quay.io/jetstack/charts/cert-manager \
--version v1.20.3 \
--namespace cert-manager \
--create-namespace \
--set crds.enabled=true \
--wait

Verify the cert-manager pods are running:

Terminal window
kubectl -n cert-manager get pods

Pass the cert-manager values override when installing or upgrading the chart:

Terminal window
helm upgrade --install openshell \
oci://ghcr.io/nvidia/openshell/helm-chart \
--version <version> \
--namespace openshell \
--set certManager.enabled=true

The chart creates a self-signed CA, issues server and client certificates from it, and cert-manager handles renewal before expiry. The chart also runs a pre-install hook in JWT-only mode to create the gateway’s sandbox JWT signing Secret. That Secret is separate from the cert-manager TLS certificate Secrets and is mounted at /etc/openshell-jwt.

Using a real Issuer for the server certificate

Section titled “Using a real Issuer for the server certificate”

By default, cert-manager issues both the server and client certificates from a self-signed CA the chart creates — this rotates automatically, but the server certificate is still not publicly trusted. certManager.serverIssuerRef overrides the issuerRef on the server Certificate resource to point at a real Issuer or ClusterIssuer instead, for example a LetsEncrypt/ACME issuer:

Terminal window
helm upgrade --install openshell \
oci://ghcr.io/nvidia/openshell/helm-chart \
--version <version> \
--namespace openshell \
--set certManager.enabled=true \
--set certManager.serverIssuerRef.name=letsencrypt-prod \
--set certManager.serverIssuerRef.kind=ClusterIssuer \
--set certManager.serverDnsNames[0]=openshell.example.com

When serverIssuerRef is set, the chart creates two server certificates:

  1. Internal certificate (openshell-server-tls): signed by the chart CA with internal SANs (*.svc.cluster.local, localhost, etc.).
  2. External certificate (openshell-server-external-tls): signed by the configured issuer (e.g. ACME) with only the hostnames from certManager.serverDnsNames.

The gateway uses SNI to select which certificate to present: supervisors connect via internal service names and receive the internal certificate (verified against the chart CA they already trust), while CLI users connecting through a Route or ingress use the external hostname and receive the ACME certificate. This keeps supervisor trust pinned to only the operator’s chart CA — no WebPKI root trust is needed.

The default clientCaFromServerTlsSecret=true is correct even when serverIssuerRef is set: the internal server certificate is always signed by the chart CA (the same CA that signs the client certificate), so its ca.crt is the right trust anchor for mTLS verification.

Return to Setup to complete the installation. For exposing the gateway externally on OpenShift with a real certificate, see OpenShift.

We are a Cloud Native Computing Foundation sandbox project.