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 name your clients will use to reach NetBox as Subject Alternative Names (SANs): the fully qualified domain name and, if clients connect by IP address, the node IP addresses. Browsers tolerate a name mismatch with a warning, but clients that verify TLS strictly (API scripts, Diode ingestion over gRPC, monitoring integrations) will 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 connecting by IP address, or by a hostname the certificate doesn't cover, are served an auto-generated certificate that changes whenever the gateway restarts, so it can't be permanently trusted or pinned. Browsers show a certificate warning, and strictly verifying clients fail to connect.

To move to a working TLS setup from this state, upload a certificate that covers your hostname and node IPs 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.

note

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 -

warning

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}"