# Ingress & TLS (/docs/enterprise/helm/configuration/ingress-tls)



Configure external access to NetBox and TLS certificate management.

## NetBox URLs [#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):

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

## Routing Mode [#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                                                                                                 |

```yaml
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](/enterprise/helm/api/netboxenterprise/#spec-routing) for details.

## Gateway Controller [#ingress-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)                                                      |

<Callout type="warn" title="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.
</Callout>

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

<Callout type="info">
  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).
</Callout>

## TLS Certificates [#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 [#using-a-pre-created-secret]

Create a TLS secret in the NetBox namespace:

```bash
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:

```yaml
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](#routing-mode).

### Using cert-manager [#using-cert-manager]

If [cert-manager](https://cert-manager.io/) 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`:

```yaml
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](#routing-mode)). This path requires Gateway API support to be enabled on your cert-manager installation.

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

## TLS Keychain [#tls-keychain]

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

```yaml
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:

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

See [PostgreSQL TLS](/enterprise/helm/configuration/postgresql/#tls-configuration) and [Redis TLS](/enterprise/helm/configuration/redis/#tls-configuration) for detailed examples.

## Extra CA Certificates [#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 [#next-steps]

* [Security](/enterprise/helm/guides/security) - TLS best practices and network policies
* [External Database](/enterprise/helm/guides/external-database) - TLS setup for external PostgreSQL