TLS and Gateway: Accessing NetBox Enterprise

NetBox Enterprise Installs

Gateway

The NetBox Enterprise installation provides its own gateway controller (Traefik, serving the Kubernetes Gateway API) on ports 80 and 443. No additional configuration is required to reach NetBox on HTTP and HTTPS.

TLS

Configuration

When you first install NetBox Enterprise and log into the Admin Console, it asks you to configure the TLS certificate. By default, it will generate a self-signed certificate, but you are able to instead upload private key and certificate chain files.

This key and certificate chain are used for any TLS connections to the cluster, whether it's the Admin Console (on port 30000) or the main NetBox interface (on port 443).

Certificate name requirements

The certificate you upload must include every DNS name your clients use to reach NetBox as a Subject Alternative Name (SAN). Have clients reach NetBox only by that name, never by IP address. A client that connects to port 443 by IP address sends no name that the gateway can match, so it gets the gateway's own self-signed default certificate, whatever certificate you upload. Browsers tolerate a name mismatch with a warning, but clients that verify TLS strictly (API scripts, Diode ingestion over gRPC, monitoring integrations) refuse to connect.

Default certificate behavior

If you skip the certificate upload (or install non-interactively, so the Admin Console prompt never appears), the gateway has no certificate matching the names your clients connect with. Clients that use your DNS name get a self-signed placeholder certificate that does not match that name. Clients that connect by IP address, or by a hostname the certificate does not cover, get an auto-generated certificate that changes whenever the gateway restarts, so it cannot be permanently trusted or pinned. Installing your own certificate fixes the first case only. Clients that connect by IP address still get the auto-generated certificate. Browsers show a certificate warning, and strictly verifying clients fail to connect.

From 2.4.0, the HTTPS Certificate on Embedded Cluster preflight and the NetBox Configuration group of the Admin Console explain this. The preflight cannot read the certificate that the gateway serves, so it shows on every Embedded Cluster install, also after you install a certificate. It always passes, so it does not block a headless install.

To move to a working TLS setup from this state, upload a certificate that covers your hostname, using the replacement steps below.

Key Replacement/Rotation

If you configured your Admin Console to use a self-signed certificate on install and wish to replace it with your own key, or if you have an existing custom key that needs rotation, you can follow these steps to do so.

Ensure you have your private key and a full certificate chain in PEM format. If you're using Let's Encrypt, this will be the privkeyXX.pem and fullchainXX.pem files. For other certificate providers, consult their documentation.

First, access the NetBox Enterprise shell:

/var/lib/embedded-cluster/bin/netbox-enterprise shell

Then, rotate the secret in place, providing the path to your chain and key files:

kubectl -n kotsadm create secret tls kotsadm-tls \
  --cert=/path/to/cert.pem --key=/path/to/key.pem \
  --dry-run=client -o yaml | kubectl -n kotsadm apply -f -

Update the secret in place. Do not delete it first. Deleting kotsadm-tls leaves the gateway's certificate reference briefly unresolved, which detaches all routes and serves a few seconds of 404s until the new secret is created. Applying over the existing secret avoids that gap.

The gateway serves the certificate from this secret directly and picks up the replacement automatically within about a minute, with no restart required. To check that the gateway pods are healthy:

kubectl -n kotsadm get pods --selector='app.kubernetes.io/name=gateway'

Finally, delete the Admin Console proxy pod, so it relaunches with the new configuration:

PROXY_POD="$(kubectl -n kotsadm get pods --selector='app==kurl-proxy-kotsadm' -o name)"
kubectl -n kotsadm delete "${PROXY_POD}"