Complete Deployment Guide

This guide walks through a full production deployment of NetBox Enterprise using the nbe-operator Helm chart. It covers every component that the Embedded Cluster sets up automatically, giving Helm users equivalent functionality with full control.

info

This guide assumes you have completed the Prerequisites. For a minimal quickstart, see Quickstart.

1. Plan Your Deployment

Before installing, decide on your component strategy:

Component	Internal (default)	External	Decision Factor
PostgreSQL	PGO-managed in-cluster	AWS RDS, Cloud SQL, etc.	Existing managed DB?
Redis	Operator-managed in-cluster	ElastiCache, etc.	Existing managed cache?
TLS	Manual secret	cert-manager	Automated certificate rotation needed?
Routing	Bundled Traefik gateway (opt-in)	Your Ingress or Gateway API controller	Existing routing infrastructure?
Monitoring	Pod annotations	ServiceMonitor	Prometheus Operator installed?

2. Prepare the Namespace and Secrets

# Create the namespace
kubectl create namespace netbox

# Log in to the Helm registry
read -rsp "License ID: " NBE_LICENSE_ID && echo
helm registry login registry.enterprise.netboxlabs.com \
  --username your-email@example.com \
  --password-stdin <<< "$NBE_LICENSE_ID"
unset NBE_LICENSE_ID

Superuser Credentials

Create a superuser secret before installation to control the initial admin account:

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>

TLS Certificate

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

3. Create the Values File

Create netbox-values.yaml with a complete production configuration:

# Enable the NetBoxEnterprise custom resource
netboxEnterprise:
  enabled: true
  spec:
    # --- NetBox Application ---
    netbox:
      replicas: 2
      resources:
        cpu: 500
        memory: 1024
      limits:
        cpu: 2000
        memory: 2048

      # URLs for ingress configuration
      urls:
        - "https://netbox.example.com"

      # Background workers
      worker:
        replicas: 2
        resources:
          cpu: 200
          memory: 256
        limits:
          cpu: 1000
          memory: 1500

      # Application settings
      config:
        metricsEnabled: true
        # Superuser from pre-created secret
        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_token

    # --- PostgreSQL (internal, PGO-managed) ---
    postgresql:
      external: false
      instances: 2
      storageSize: "20Gi"

    # --- Redis (internal, operator-managed) ---
    redis:
      external: false
      clusterSize: 3

    # --- Diode Data Ingestion ---
    diode:
      enabled: true
      config:
        reconciler:
          # autoApplyChangesets: true  # false recommended if using Assurance

Using External PostgreSQL Instead

If you have an existing managed database, replace the postgresql section:

    postgresql:
      external: true
      host: "your-rds-instance.region.rds.amazonaws.com"
      port: 5432
      database:
        name: external-db-secret
        key: database
      username:
        name: external-db-secret
        key: username
      password:
        name: external-db-secret
        key: password

See External Database and PostgreSQL Configuration for full details.

Using External Redis Instead

    redis:
      external: true
      host: "your-redis.cache.amazonaws.com"
      port: 6379
      password:
        name: external-redis-secret
        key: password

See Redis Configuration for full details.

4. Install CRDs and the Operator

Install the CRDs first, then the operator chart:

# Install Custom Resource Definitions
helm install nbe-crds \
  oci://registry.enterprise.netboxlabs.com/library/netbox-enterprise-crds \
  --namespace netbox

# Install the operator with your values
helm install netbox-enterprise \
  oci://registry.enterprise.netboxlabs.com/library/nbe-operator \
  --namespace netbox \
  --values netbox-values.yaml

5. Verify the Deployment

Watch pods come up

kubectl -n netbox get pods -w

You should see pods for:

• netbox-enterprise-nbe-operator-*: the operator
• netbox-*: NetBox application replicas
• netbox-worker-*: background workers
• postgres-cluster-*: PGO-managed PostgreSQL (if internal)
• redis-*: Redis instances (if internal)

Check the NetBoxEnterprise status

kubectl -n netbox get netboxenterprises -o wide

When the READY column shows True, your deployment is healthy.

Inspect detailed conditions

kubectl -n netbox describe netboxenterprise netbox

Look for:

Conditions:
  Type        Status  Reason
  ----        ------  ------
  Ready       True    AllComponentsReady
  Progressing False   ReconcileComplete

See Status & Conditions for the full list of conditions.

6. Configure Monitoring

Option A: Pod Annotations (default)

The chart adds Prometheus scrape annotations by default (metrics.podAnnotations: true). If your Prometheus is configured to scrape annotated pods, metrics are available immediately.

Option B: ServiceMonitor

If you use the Prometheus Operator, enable a ServiceMonitor:

serviceMonitor:
  enabled: true
  interval: 30s
  labels:
    release: prometheus  # Match your Prometheus selector

See Monitoring for application-level metrics details.

7. Set Up Backups

For production deployments, configure Velero for cluster backups:

netboxEnterprise:
  spec:
    backups: true

See Backups for Velero setup instructions.

8. Access NetBox

Via port-forward (testing)

kubectl -n netbox port-forward svc/netbox 8080:8080
# Open http://localhost:8080

Via ingress or gateway (production)

If you configured netbox.urls, the operator creates routing resources automatically. In the default ingress mode, verify the Ingress:

kubectl -n netbox get ingress

If routing resolves to gateway mode, the operator creates Gateway API routes instead:

kubectl -n netbox get httproute

See Ingress & TLS for routing modes and advanced configuration.

Next Steps

• Architecture: Understand the component topology
• Security: RBAC modes, pod security, and TLS hardening
• Maintenance Mode: Safely perform maintenance operations
• Upgrading: Upgrade to new chart versions
• Helm Values Reference: All available configuration options