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
Section titled “Install cert-manager”Install cert-manager from the OCI registry with CRD support enabled:
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 \ --waitVerify the cert-manager pods are running:
kubectl -n cert-manager get podsInstall OpenShell with cert-manager PKI
Section titled “Install OpenShell with cert-manager PKI”Pass the cert-manager values override when installing or upgrading the chart:
helm upgrade --install openshell \ oci://ghcr.io/nvidia/openshell/helm-chart \ --version <version> \ --namespace openshell \ --set certManager.enabled=trueThe 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:
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.comDual certificate architecture
Section titled “Dual certificate architecture”When serverIssuerRef is set, the chart creates two server certificates:
- Internal certificate (
openshell-server-tls): signed by the chart CA with internal SANs (*.svc.cluster.local,localhost, etc.). - External certificate (
openshell-server-external-tls): signed by the configured issuer (e.g. ACME) with only the hostnames fromcertManager.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.
Next Steps
Section titled “Next Steps”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.
Copyright OpenShell a Series of LF Projects, LLC
For website terms of use, trademark policy and other project policies please see lfprojects.org/policies/.