Standard Installation
Full NetBox Enterprise installation with custom values and production settings
Installation Journey Prerequisites → Standard Installation (you are here) → Configure
This guide walks through a production-ready NetBox Enterprise installation with a custom values file, TLS, resource configuration, and post-install verification.
Installing on OpenShift? Follow this guide with the changes in On OpenShift.
1. Create a Values File
Create netbox-values.yaml with your configuration:
# Enable the NetBoxEnterprise custom resource
netboxEnterprise:
enabled: true
spec:
# NetBox application
netbox:
replicas: 2 # requires shared storage — see note below
resources:
cpu: 500
memory: 1024
limits:
cpu: 2000
memory: 2048
worker:
replicas: 2
resources:
cpu: 200
memory: 256
limits:
cpu: 1000
memory: 1500
config:
metricsEnabled: true
# Internal PostgreSQL (default)
postgresql:
external: false
instances: 2 # Redundant with 2 replicas
storageSize: "20Gi"
# Internal Redis (default)
redis:
external: false
clusterSize: 3
# Diode data ingestion
diode:
enabled: true
config:
reconciler:
# autoApplyChangesets: true # false recommended if using AssuranceMultiple replicas require shared storage
This example sets netbox.replicas: 2. The media and scripts PVCs default to ReadWriteOnce and cannot be shared across nodes, so multi-replica deployments need either S3 media storage (recommended) or ReadWriteMany PVCs first. See Multi-Replica Storage.
2. Create the Namespace
kubectl create namespace netbox3. Configure Superuser (Optional)
By default the operator auto-generates a superuser with the username admin and a random password. To use your own credentials instead, create a secret before installing:
kubectl -n netbox create secret generic netbox-superuser \
--from-literal=username=admin \
--from-literal=email=admin@example.com \
--from-literal=password=<secure-password> \
--from-literal=api_token=<your-api-token>Then add to your values file:
netboxEnterprise:
spec:
netbox:
config:
superuser:
username:
name: netbox-superuser
key: username
email:
name: netbox-superuser
key: email
password:
name: netbox-superuser
key: password
apiToken:
name: netbox-superuser
key: api_tokenSuperuser credentials are only applied during the initial database setup. If you skip this step, you can retrieve the auto-generated password later.
4. Configure TLS (Optional)
To serve NetBox over HTTPS, create a TLS secret:
kubectl -n netbox create secret tls netbox-tls \
--cert=path/to/tls.crt \
--key=path/to/tls.keyAdd URLs to your values file so the operator configures routing:
netboxEnterprise:
spec:
netbox:
urls:
- "https://netbox.example.com"See Ingress & TLS for detailed configuration options.
5. Install CRDs
Install the three Custom Resource Definition charts before the operator:
helm install netbox-enterprise-crds \
oci://registry.enterprise.netboxlabs.com/netbox-enterprise/stable-v2/netbox-enterprise-crds \
--version 2.5.0 \
--namespace netbox
helm install netbox-enterprise-crds-pgo \
oci://registry.enterprise.netboxlabs.com/netbox-enterprise/stable-v2/netbox-enterprise-crds-pgo \
--version 2.5.0 \
--namespace netbox
helm install netbox-enterprise-crds-redis \
oci://registry.enterprise.netboxlabs.com/netbox-enterprise/stable-v2/netbox-enterprise-crds-redis \
--version 2.5.0 \
--namespace netboxUsing the bundled gateway?
These three CRD charts cover a default installation, which routes through your existing ingress controller. If you plan to enable the bundled Traefik gateway (gateway.enabled: true), install the Gateway API CRD charts as well. See Gateway API CRDs.
On OpenShift, install only these three charts. See On OpenShift.
Turning on the bundled Keycloak?
The bundled Keycloak identity provider needs three things: the chart value idp.enabled: true, which installs the Keycloak operator; netboxEnterprise.spec.idp.enabled: true, which creates Keycloak; and Gateway routing. With Ingress routing, the default on this page and the documented OpenShift path, Keycloak is not deployed and the IdentityProvider condition reports PendingHost. See Platform Single Sign-On.
Keycloak takes its hostname from an enabled Gateway. Under Ingress routing it has no hostname, even when netbox.urls names one. Add these values to turn on Keycloak and Gateway routing with an HTTPS listener:
idp:
enabled: true
gateway:
enabled: true # The bundled Traefik controller. Leave it out if you run your own.
netboxEnterprise:
spec:
idp:
enabled: true
routing:
mode: gateway
gateway:
enabled: true
listeners:
- name: web
port: 80
protocol: HTTP
hostname: netbox.example.com
- name: websecure
port: 443
protocol: HTTPS
hostname: netbox.example.com
tls:
mode: Terminate
certificateRefs:
- name: netbox-tls- Set
hostnameto the name your users open NetBox at. Do not use a wildcard such as*.example.com. Keycloak cannot build its sign-in address from a wildcard. netbox-tlsis the TLS secret from step 4.- The bundled Traefik controller also needs the Gateway API CRD charts. See Gateway API CRDs.
- If you run your own Gateway API controller, set
netboxEnterprise.spec.gateway.classNameto itsGatewayClass. - Gateway routing replaces Ingress routing. On an existing install, the upgrade that turns it on deletes the NetBox, Diode and Copilot Ingress objects the operator created. Plan a short cutover, and point your DNS at the Gateway after that upgrade. The bundled Traefik controller serves on ports 80 and 443 of every node.
Without these values, Keycloak is not deployed, and the IdentityProvider condition is False with reason PendingHost. Ready can still be True. The check in Inspect detailed status shows it.
The Keycloak operator needs the Keycloak CRDs, which none of the three charts above carries. Install this chart as well, before the operator:
helm install netbox-enterprise-crds-keycloak \
oci://registry.enterprise.netboxlabs.com/netbox-enterprise/stable-v2/netbox-enterprise-crds-keycloak \
--version 2.5.0 \
--namespace netbox6. Install the Operator
helm install netbox-enterprise \
oci://registry.enterprise.netboxlabs.com/netbox-enterprise/stable-v2/netbox-enterprise \
--version 2.5.0 \
--namespace netbox \
--values netbox-values.yaml7. Apply Configuration
Apply a NetBoxEnterprise resource manifest. The example manifests use namespace: default, but the manifest must be in the same namespace as your Helm install so that pods can access the image pull secret. Use curl and sed to substitute the namespace in one step:
curl -sL https://netboxlabs.com/docs/files/helm/examples/netbox-managed.yaml \
| sed 's/namespace: default/namespace: netbox/' \
| kubectl apply -f -If you used a different namespace, replace netbox in the sed expression to match.
See the available examples for manifests covering external databases, SSO, object storage, and more; apply the same sed substitution to any of them.
8. Verify the Installation
Check pod status
kubectl -n netbox get podsAll pods should reach Running (or Completed for jobs) within a few minutes.
Check NetBoxEnterprise status
kubectl -n netbox get netboxenterprises -o wideInspect detailed status
kubectl -n netbox describe netboxenterprise netbox-managedLook for the Ready condition with status True:
Conditions:
Type Status Reason
---- ------ ------
Ready True AllComponentsReady
Progressing False ReconcileCompleteIf you turned on the bundled Keycloak, also check the IdentityProvider condition. No IdentityProvider reason gates Ready, so Ready can be True while sign-in is not set up. A working identity provider reports True with reason Provisioned:
kubectl -n netbox get netboxenterprise netbox-managed \
-o jsonpath='{.status.conditions[?(@.type=="IdentityProvider")].status} {.status.conditions[?(@.type=="IdentityProvider")].reason}{"\n"}'Check operator logs
kubectl -n netbox logs -l app.kubernetes.io/name=nbe-operator --tail=50Platform Notes
On OpenShift
Private Preview
OpenShift support is in Private Preview in NetBox Enterprise 2.5.0. Contact Customer Support for OpenShift deployments. More OpenShift support work is planned for later releases.
Check the OpenShift requirements first. A cluster administrator runs this install. An install without cluster-admin access follows Namespace-Scoped Installation instead, which installs only netbox-enterprise-crds, not the three CRD charts below. The steps above apply on OpenShift with two changes.
CRD charts
In step 5, install netbox-enterprise-crds, netbox-enterprise-crds-pgo, and netbox-enterprise-crds-redis. Do not install netbox-enterprise-crds-gateway: OpenShift ships and manages the Gateway API CRDs. Leave gateway.enabled at its default, false.
Routing through the OpenShift router
The default Ingress class, nginx, does not exist on OpenShift. Add these values to netbox-values.yaml so the OpenShift router serves NetBox:
netboxEnterprise:
spec:
netbox:
urls:
- "https://netbox.apps.<cluster-domain>"
ingress:
className: openshift-default
tls:
- {}className: openshift-defaultmakes the router admit the NetBox Ingress and create a Route for it.- The host in
urlsmust be under the cluster's apps domain. The router creates no Route for an Ingress rule without a host. To find the apps domain, runoc get ingresses.config.openshift.io cluster -o jsonpath='{.spec.domain}'. - The empty TLS entry,
{}, terminates TLS at the router edge with the router's default certificate. To serve your own certificate, setsecretNamein that entry to the name of a TLS secret in the install namespace.
If you create your own edge Route instead, set its target port to the Service port name, http. The port number 80 does not work.
Only NetBox is served through the OpenShift router in 2.5.0. The operator creates the Diode and Copilot Ingresses for the nginx class only, so Diode and Copilot are not routed on OpenShift. See Ingress & TLS.
To check the route after the install, run:
oc -n netbox get routesThe NetBox host from urls is listed. Open https://<host>/login/ to reach the NetBox login page.
When the router admits the Route, OpenShift writes the router's hostname to the NetBox Ingress status, and the RoutingHealth condition on the NetBoxEnterprise resource changes to True with reason IngressActive. After you change the routing values, allow up to about 5 minutes for RoutingHealth to update: the operator first waits for the NetBox rollout.
Until the Ingress has an address, RoutingHealth is Unknown with reason IngressPending. If the Ingress still has no address 5 minutes after it was created, RoutingHealth becomes Unknown with reason IngressNotAdmitted, and the operator records one Warning event. Either reason means the router has not admitted the Ingress. Check that className is openshift-default and that urls names a host under the apps domain.
Next Steps
- Helm Values Reference: Explore all available configuration options
- Security: RBAC modes, pod security, and TLS hardening
- Monitoring: Set up Prometheus metrics and ServiceMonitor