NetBox Configuration

Configure the NetBox web application and background workers under netboxEnterprise.spec.netbox.

Application Deployment

Image

Resources

Resources are specified in millicores (CPU) and mebibytes (memory):

Storage

Multi-Replica Storage

Option 1 — S3 media storage (recommended). Move uploaded media to S3-compatible object storage, so no shared filesystem is required:

netbox:
  replicas: 2
  config:
    storage:
      s3:
        enabled: true
        bucketName: netbox-media
        endpointUrl: https://s3.example.com  # omit for AWS S3
        accessKeyId:
          name: netbox-s3-creds
          key: access_key
        secretAccessKey:
          name: netbox-s3-creds
          key: secret_key

See S3 Media Storage below for the full field list and TLS options.

Option 2 — ReadWriteMany PVCs. Keep media on PVCs, but back them with an RWX-capable storage class (NFS, CephFS, Amazon EFS, and similar):

netbox:
  replicas: 2
  storageAccessMode: ReadWriteMany
  storageClassName: nfs-rwx  # an RWX-capable class in your cluster

Recreate the PVCs in the new access mode in this order, so the mounting pods release the volumes first and the operator recreates them in the new mode rather than the old one:

1. Back up the media and scripts PVC contents (see Backups).
2. Confirm an RWX-capable StorageClass exists in the cluster. Do not change netbox.storageClassName yet — that happens in step 4, because it is immutable on the existing PVCs (see below).
3. Scale the workloads down to release the volumes, with reconciliation still active (leave spec.suspend unset): set netbox.replicas: 0 and netbox.worker.replicas: 0, then wait for the web and worker pods to terminate. Both mount these PVCs, so all of them must stop — a kubectl delete pvc while any pod still mounts the volume hangs in Terminating. Change only the replica counts here; leave the access mode and storage class unchanged so this update applies cleanly.
4. Pause reconciliation, then set the new storage fields: set spec.suspend: true, then set netbox.storageAccessMode: ReadWriteMany and netbox.storageClassName to the RWX class. Suspending is required: storageAccessMode and storageClassName are immutable on an existing PVC, so while the old ReadWriteOnce PVCs still exist an active reconcile would error trying to change them — and would recreate a just-deleted PVC in the old mode. Suspend holds the operator until the old PVCs are gone.
5. Delete the now-unmounted PVCs: kubectl -n netbox delete pvc <name>-netbox-media <name>-netbox-scripts, where <name> is your NetBoxEnterprise resource name — confirm the exact names with kubectl -n netbox get pvc.
6. Resume: clear spec.suspend and restore netbox.replicas / netbox.worker.replicas. The operator recreates both PVCs with the new access mode and storage class, and brings the pods back.
7. Restore the backed-up media and scripts into the new volumes.

URLs

Example:

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

Environment Variables

Worker Configuration

Background workers process asynchronous tasks such as webhooks, reports, and scripts.

Application Config

Settings under netbox.config control NetBox application behavior.

Superuser

If provided, all four fields must be set. Each references a Kubernetes Secret:

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_token

If no superuser is configured, the operator auto-generates credentials with the username admin and a random password.

Retrieving Auto-Generated Credentials

The auto-generated superuser secret follows the naming pattern <netboxenterprise-name>-netbox-superuser. For the default NetBoxEnterprise name netbox:

kubectl -n netbox get secret netbox-netbox-superuser \
  -o jsonpath='{.data.password}' | base64 -d ; echo

To retrieve the auto-generated API token:

kubectl -n netbox get secret netbox-netbox-superuser \
  -o jsonpath='{.data.api_token}' | base64 -d ; echo

Secret Key

The Django secret key is auto-generated if not provided. To use a specific key:

netbox:
  config:
    secretKey:
      name: netbox-django-secret
      key: secret_key

S3 Media Storage

Store uploaded files in S3-compatible object storage instead of local PVCs:

netbox:
  config:
    storage:
      s3:
        enabled: true
        bucketName: netbox-media
        regionName: us-east-1
        endpointUrl: https://s3.example.com  # for MinIO, Garage, etc.
        accessKeyId:
          name: netbox-s3-creds
          key: access_key
        secretAccessKey:
          name: netbox-s3-creds
          key: secret_key

S3 TLS Configuration

For S3-compatible endpoints with custom CA certificates or mTLS, use the tlsConfig field which references certificates from the cluster's tlsKeychain:

netbox:
  config:
    storage:
      s3:
        enabled: true
        bucketName: netbox-media
        endpointUrl: https://minio.internal:9000
        tlsConfig:
          keychainCaCertificates:
            - minio-ca
          keychainClientCertificate: minio-client  # for mTLS

Scaling Guidance

NetBox replica counts may be constrained by your license tier:

• Community / Starter: Up to the tier's replica limit
• Professional / Premium: Higher limits or uncapped

The operator respects these limits and surfaces warnings in the NetBoxEnterprise status if the configured replica count exceeds the licensed maximum.

Next Steps

• PostgreSQL - Database configuration
• Monitoring - Enable application metrics
• NetBoxEnterprise CRD - Full spec reference