Ingress & TLS

Configure external access to NetBox and TLS certificate management.

NetBox URLs

Set netbox.urls to define the external URLs where NetBox is accessible. The operator uses these to configure routing resources (Gateway API routes or Ingresses):

netboxEnterprise:
  spec:
    netbox:
      urls:
        - "https://netbox.example.com"

Routing Mode

The operator serves external traffic through either the Kubernetes Gateway API or Ingress resources. The path is selected by spec.routing.mode:

Mode	Behavior
auto (default)	Emit Gateway API resources when spec.gateway is enabled and the Gateway API CRDs are installed, Ingress resources otherwise
gateway	Always emit Gateway API resources (Gateway, HTTPRoute, GRPCRoute)
ingress	Always emit Ingress resources

netboxEnterprise:
  spec:
    routing:
      mode: auto

With the default auto mode, a cluster without the Gateway API keeps working unchanged: the operator emits Ingress resources for your existing ingress controller. See the CRD reference for details.

Gateway Controller

The chart includes an optional Traefik gateway controller (subchart alias gateway) for environments that don't already have a Gateway API controller. It runs as a hostNetwork DaemonSet binding node ports 80 and 443, and creates the traefik GatewayClass that the operator's Gateway references by default.

Key	Type	Default	Description
gateway.enabled	bool	false	Deploy the bundled Traefik gateway controller
gateway.deployment.kind	string	DaemonSet	Controller deployment type (every node serves 80/443)
gateway.deployment.dnsPolicy	string	ClusterFirstWithHostNet	Pod DNS policy, paired with host networking
gateway.hostNetwork	bool	true	Bind node ports 80/443 directly instead of using a LoadBalancer
gateway.ports.web.port	int	80	HTTP entry point. Under host networking this is the host bind port and must match the operator's Gateway listener port.
gateway.ports.websecure.port	int	443	HTTPS entry point. Same matching rule as web.
gateway.gatewayClass.enabled	bool	true	Create the traefik GatewayClass
gateway.providers.kubernetesGateway.enabled	bool	true	Serve the Gateway API (HTTPRoute/GRPCRoute)
gateway.service.spec.type	string	ClusterIP	Controller Service type (host networking handles external traffic)

Gateway API CRDs are a prerequisite

Enabling gateway.enabled: true requires the Gateway API CRDs in the cluster. Install the netbox-enterprise-crds-gateway chart before the main chart. Skip it if you bring your own Gateway API controller (your cluster already has the CRDs) or stay on the Ingress path.

For most deployments, use your cluster's existing ingress or Gateway API controller and leave gateway.enabled: false.

tip

If you already have an ingress controller (e.g., ingress-nginx, Traefik, or a cloud load balancer), you don't need to enable the bundled one. Set netbox.urls and the operator creates the appropriate Ingress resource (or Gateway API routes, if routing resolves to gateway mode).

TLS Certificates

To serve NetBox over HTTPS, create a TLS secret and reference it from the routing resource. Setting netbox.urls on its own does not enable TLS. netbox.urls only sets the hostnames the operator routes; the TLS secret must be referenced explicitly.

Using a Pre-Created Secret

Create a TLS secret in the NetBox namespace:

kubectl -n netbox create secret tls netbox-tls \
  --cert=path/to/tls.crt \
  --key=path/to/tls.key

In ingress routing mode, reference the secret from spec.ingress.tls, listing the hostnames it covers and the secret name:

netboxEnterprise:
  spec:
    ingress:
      tls:
        - hosts:
            - netbox.example.com
          secretName: netbox-tls
    netbox:
      urls:
        - "https://netbox.example.com"

The hostnames under ingress.tls.hosts must match those in netbox.urls.

In gateway routing mode, TLS is terminated at the Gateway listener instead. Configure it through spec.gateway.listeners[].tls (standard Gateway API listener TLS), not spec.ingress.tls. See Routing Mode.

Using cert-manager

If cert-manager is installed in your cluster, it can provision and renew the certificate automatically. Where the issuer annotation goes depends on the routing mode. A top-level netboxEnterprise.annotations value lands on the NetBoxEnterprise resource's own metadata, which the operator does not copy onto the routing resources, so cert-manager never sees it. Set the annotation on the routing resource instead.

In ingress routing mode, annotate the operator-emitted Ingress through spec.ingress.annotations, and name the secret for cert-manager to populate in spec.ingress.tls:

netboxEnterprise:
  spec:
    ingress:
      annotations:
        cert-manager.io/cluster-issuer: letsencrypt-prod
      tls:
        - hosts:
            - netbox.example.com
          secretName: netbox-tls
    netbox:
      urls:
        - "https://netbox.example.com"

In gateway routing mode, annotate the Gateway through spec.gateway.annotations. cert-manager then writes the certificate to the secret referenced by the listener's tls.certificateRefs (see Routing Mode). This path requires Gateway API support to be enabled on your cert-manager installation.

netboxEnterprise:
  spec:
    gateway:
      annotations:
        cert-manager.io/cluster-issuer: letsencrypt-prod

TLS Keychain

The tlsKeychain provides a centralized way to manage CA and client certificates referenced by PostgreSQL, Redis, and Hydra TLS configurations:

netboxEnterprise:
  spec:
    tlsKeychain:
      caCertificateSecrets:
        - name: postgres-ca         # Logical name referenced in tlsConfig
          secret: my-pg-ca-secret   # Kubernetes secret name (defaults to name)
          key: ca.crt               # Key within the secret (default: ca.crt)
      clientCertificateSecrets:
        - name: postgres-client
          secret: my-pg-client-cert
          certKey: tls.crt          # Certificate key (default: tls.crt)
          privateKey: tls.key       # Private key (default: tls.key)

Then reference these by name in component TLS configurations:

    postgresql:
      external: true
      tlsConfig:
        sslmode: verify-full
        keychainCaCertificates:
          - postgres-ca
        keychainClientCertificate: postgres-client

See PostgreSQL TLS and Redis TLS for detailed examples.

Extra CA Certificates

Use netboxEnterprise.spec.extraCaCertificates to add PEM-encoded CA certificates to the trust bundle used by NetBox and the operator. This is separate from tlsKeychain, which scopes certificates to individual component connections.

Key	Type	Default	Description
netboxEnterprise.spec.extraCaCertificates	list	[]	Additional trusted CA certificates (PEM) added to the system trust bundle

Next Steps

• Security - TLS best practices and network policies
• External Database - TLS setup for external PostgreSQL