NetBoxEnterprise CRD

The NetBoxEnterprise custom resource defines a complete NetBox Enterprise deployment. The nbe-operator watches these resources and reconciles them into the appropriate Kubernetes objects.

API Details:

Field	Value
Group	`netboxlabs.com`
Versions	`v1alpha2` (storage), `v1alpha1` (served)
Kind	`NetBoxEnterprise`
Scope	Namespaced
Short name	`nbe`

NetBox Enterprise 2.2.0 introduced the v1alpha2 schema as the storage version. The older v1alpha1 schema is still served in 2.3.0, so existing manifests keep applying unchanged. The two versions carry the same JSON wire shape -- v1alpha2 is v1alpha1 with the defaulted fields made optional. No conversion webhook exists, and none is needed. A one-time storage migration runs at operator startup and re-encodes stored resources as v1alpha2. No action is required. The examples below use v1alpha2.

Full CRD: netboxenterprises.netboxlabs.com-v2.3.0.yaml

Minimal Example

apiVersion: netboxlabs.com/v1alpha2
kind: NetBoxEnterprise
metadata:
  name: netbox
  namespace: netbox
spec:
  netbox:
    replicas: 1
    worker:
      replicas: 1
  postgresql:
    external: false
  redis:
    external: false

Full Example

apiVersion: netboxlabs.com/v1alpha2
kind: NetBoxEnterprise
metadata:
  name: netbox
  namespace: netbox
spec:
  suspend: false
  maintenanceMode: false

  labels:
    app.kubernetes.io/managed-by: netbox-operator

  imagePullSecrets:
    - netbox-enterprise-registry

  netbox:
    replicas: 2
    httpPort: 8080
    mediaStorageSize: "10Gi"
    urls:
      - "https://netbox.example.com"
    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
      allowedHosts:
        - "*"

  postgresql:
    external: false
    instances: 2
    version: "18"
    storageSize: "20Gi"
    resources:
      cpu: 500
      memory: 1024
    limits:
      cpu: 2000
      memory: 2048
    backups:
      enabled: true
      repoStorageSize: "16Gi"
      retentionFull: 4
      fullSchedule: "0 1 * * 0"
      incrementalSchedule: "0 1 * * 1-6"

  redis:
    external: false
    clusterSize: 3
    persistence: true
    storageSize: "2Gi"
    resources:
      cpu: 250
      memory: 256
    limits:
      cpu: 500
      memory: 512

  diode:
    enabled: true
    reconciler:
      replicas: 1
    ingester:
      replicas: 1
    auth:
      replicas: 1
    hydra:
      replicas: 1
    config:
      reconciler:
        # autoApplyChangesets: true  # false recommended if using Assurance
        logLevel: INFO

Spec Reference

Top-Level Fields

Field	Type	Default	Description
`suspend`	bool	`false`	Pause reconciliation - existing workloads keep running
`maintenanceMode`	bool	`false`	Scale down all app components, keep databases running
`labels`	map[string]string	-	Labels applied to all managed resources
`annotations`	map[string]string	-	Annotations applied to all managed resources
`imagePullPolicy`	string	`IfNotPresent`	Default image pull policy
`imagePullSecrets`	[]string	-	Pull secrets for private registries
`registry`	string	-	Container registry host override for all images
`registryNamespace`	string	-	Registry namespace for flat-namespace registries (e.g., airgap). When set alongside `registry`, repository paths are flattened to `{namespace}/{basename}`
`clusterDnsSuffix`	string	-	Kubernetes cluster DNS suffix (defaults to `cluster.local`)
`reconcileInterval`	string	unset (operator falls back to 5m)	How often the operator re-checks external state when no Kubernetes events are received. Covers changes that do not produce watch events (PGO secret rotations, wheelhouse uploads). Kubernetes-style duration string (`30s`, `1m`, `5m`) or bare seconds.
`secretChecksumDebounce`	string	unset (operator falls back to 30s)	Debounce window for embedding external secret `resourceVersion` into pod template annotations. Prevents PGO housekeeping writes from triggering rolling restarts. Kubernetes-style duration string or bare seconds. Lower values speed up convergence in test environments; raise it for slow-bootstrapping clusters.
`backups`	bool	`false`	Enable Velero backups for this cluster. Requires Velero installed in the cluster. This is the cluster-wide Velero switch. It does not control the PostgreSQL backups -- see `spec.postgresql.backups`.
`storageBackend`	enum	`pvc`	Where NetBox media and script files live. See `spec.storageBackend`.
`extraManifests`	[]string	-	Extra Kubernetes manifests to apply beside the managed workloads. See `spec.extraManifests`.

Each operator-managed workload section (spec.netbox, spec.netbox.worker, spec.copilot, and each spec.diode.<component>) accepts a topologySpreadConstraints array using the standard Kubernetes type. A cluster-wide default lives at spec.replication.topologySpreadConstraints. The operator auto-injects hostname spread for Redis replication and Sentinel; user-set constraints are honored as-is.

`spec.replication`

Cluster-wide replication and placement settings.

Field	Type	Default	Description
`topologySpreadConstraints`	[]TopologySpreadConstraint	-	Default constraints applied to every operator-managed deployment. A per-component `topologySpreadConstraints` field replaces this default for that component. The operator injects each deployment's own selector labels into every constraint's `labelSelector`, so one block covers every workload.

replication:
  topologySpreadConstraints:
    - maxSkew: 1
      topologyKey: kubernetes.io/hostname
      whenUnsatisfiable: ScheduleAnyway

`spec.proxy`

Egress proxy settings. When set, the operator injects HTTP_PROXY, HTTPS_PROXY, and NO_PROXY into every workload it creates (NetBox, workers, Copilot, Diode, Hydra, migrations, the operator, and the Replicated SDK). When omitted, no proxy is configured. On Embedded Cluster and KOTS installs the proxy is inherited from the install-time proxy flags and shown read-only in the Admin Console; raw Helm installs set it here.

proxy:
  httpProxy: http://proxy.corp:3128
  httpsProxy: http://proxy.corp:3128
  noProxy: .internal.example.com,10.0.0.0/8

Field	Type	Default	Description
`httpProxy`	string	-	HTTP proxy URL (e.g. `http://proxy.corp:3128`)
`httpsProxy`	string	-	HTTPS proxy URL. Used for license, S3, and external HTTPS egress.
`noProxy`	string	-	Comma-separated extra `NO_PROXY` entries, appended to the cluster-internal defaults the operator always includes

`spec.postgresqlProfiles`

Named PostgreSQL connection profiles that components can reference by name. This avoids duplicating host, port, and TLS settings across components when they share the same database server.

postgresqlProfiles:
  netbox:
    host: db.example.com
    port: 5432
    username: netbox
    tlsConfig:
      sslmode: verify-full
      keychainCaCertificates: ['pgo']

Field	Type	Default	Description
`postgresqlProfiles.<name>.host`	string	-	PostgreSQL hostname
`postgresqlProfiles.<name>.port`	integer	-	PostgreSQL port
`postgresqlProfiles.<name>.username`	string	-	PostgreSQL username
`postgresqlProfiles.<name>.tlsConfig`	object	-	TLS configuration (see PostgreSQL TLS)

PostgreSQL Profile `tlsConfig`

Field	Type	Default	Description
`sslmode`	enum	`prefer`	`disable`, `allow`, `prefer`, `require`, `verify-ca`, `verify-full`
`insecureSkipVerify`	bool	`false`	Skip TLS verification
`keychainCaCertificates`	[]string	-	CA names from `tlsKeychain`
`keychainClientCertificate`	string	-	Client cert name from `tlsKeychain`

When CA certificates are configured via keychainCaCertificates, libpq verifies the server certificate even with sslmode: require (effectively upgrading it to verify-ca behavior). This is because the operator sets PGSSLROOTCERT when CA certificates are provided. If you need require without verification, omit the CA certificates.

`spec.netbox`

Required. NetBox application deployment configuration.

Field	Type	Default	Description
`replicas`	integer	`1`	Web application replicas
`httpPort`	integer	`8080`	HTTP port
`statusPort`	integer	-	Deprecated. Health check port. Ignored since granian in nbe-core 4.5.x.
`mediaStorageSize`	string	`10Gi`	Media PVC size
`scriptsStorageSize`	string	`1Gi`	Scripts PVC size
`migrationTimeout`	string	`1h`	Maximum time for the migration Job to run before Kubernetes terminates it. Accepts durations (`1h`, `30m`) or bare seconds (`3600`).
`migrationStatementTimeout`	string	`15m`	Per-statement timeout for index reconciliation. Prevents a single slow index creation from consuming the entire job deadline. Accepts durations or bare seconds.
`appReadyTimeout`	string	`5m`	Maximum time the operator waits for the NetBox app deployment to become ready after each reconcile. Covers database migrations run at pod startup. Accepts durations (`5m`, `300s`) or bare seconds.
`storageClassName`	string	-	Storage class override
`storageAccessMode`	enum	`ReadWriteOnce`	Access mode for the media and scripts PVCs: `ReadWriteOnce`, `ReadOnlyMany`, `ReadWriteMany`, or `ReadWriteOncePod`. Use `ReadWriteMany` with an RWX-capable `storageClassName` to spread `replicas > 1` across nodes, or move media to S3 via `config.storage`.
`urls`	[]string	-	External URLs (configures ingress)
`resources.cpu`	int	`200`	CPU request (millicores)
`resources.memory`	int	`750`	Memory request (MiB)
`limits.cpu`	int	`1000`	CPU limit (millicores)
`limits.memory`	int	`1500`	Memory limit (MiB)
`env`	[]EnvVar	-	Environment variables
`yamlEnv`	string	-	YAML string of env vars
`timeouts`	object	-	Per-service timeout overrides for the NetBox Ingress and HTTPRoute. See `spec.netbox.timeouts`.
`topologySpreadConstraints`	[]TopologySpreadConstraint	-	Pod spread constraints for the NetBox web pods. Replaces `spec.replication.topologySpreadConstraints` for this workload.

`spec.netbox.image`

Field	Type	Default	Description
`registry`	string	`docker.io`	Container registry
`repository`	string	`netboxcommunity/netbox`	Image repository
`tag`	string	`v4.6.8`	Image tag. The default tracks the NetBox version this release ships.
`digest`	string	-	Image digest for pinning
`pullPolicy`	string	`IfNotPresent`	Pull policy
`imagePullSecrets`	[]LocalObjectReference	-	Pull secrets for this image only. Adds to the cluster-wide `spec.imagePullSecrets`.

`spec.netbox.timeouts`

Per-service timeout overrides for NetBox. Each field merges over the matching cluster-wide default in spec.ingress.timeouts or spec.gateway.timeouts. When the section is omitted, the cluster-wide defaults apply unchanged.

Field	Type	Default	Description
`ingress.connect`	string	-	Time allowed to open a TCP connection to the NetBox pods.
`ingress.read`	string	-	Time between successive reads from the NetBox response.
`ingress.send`	string	-	Time between successive writes to the NetBox request.
`gateway.request`	string	-	Maximum time the gateway waits for a complete NetBox response. Gateway API duration, such as `60s` or `1m30s`.
`gateway.backendRequest`	string	-	Maximum time for one request attempt to the NetBox backend.

The same five fields exist on spec.copilot.timeouts, on spec.diode.timeouts.http, and (the three ingress fields only) on spec.diode.timeouts.grpc.

`spec.netbox.diodePlugin`

NetBox-side deadlines for outbound calls to Diode. Tune these when raising the cluster-wide ingress/gateway timeouts so the app layer does not cap the higher ingress bound.

Field	Type	Default	Description
`authTimeout`	string	runtime `500ms`	Timeout for Hydra token introspection calls from the NetBox plugins.
`grpcTimeout`	string	runtime `5s`	Timeout for Diode gRPC calls from the NetBox plugins.

`spec.netbox.worker`

Field	Type	Default	Description
`replicas`	integer	`1`	Worker replicas (0-255). Operator-applied default when unset.
`resources.cpu`	int	`100`	CPU request (millicores)
`resources.memory`	int	`128`	Memory request (MiB)
`limits.cpu`	int	`1000`	CPU limit (millicores)
`limits.memory`	int	`1500`	Memory limit (MiB)
`env`	[]EnvVar	-	Environment variables for worker containers. Merged with `yamlEnv`.
`yamlEnv`	string	-	YAML string of env vars (e.g. `"FOO: bar\nBAZ: qux"`)
`affinity`	object	-	Pod affinity for worker pods. When omitted, the operator binds each worker to a NetBox pod (`kubernetes.io/hostname`) only when `replicas == 1` and `storageAccessMode` is unset, `ReadWriteOnce`, or `ReadWriteOncePod`, so the worker can mount the same single-node media and scripts PVCs. Set an explicit `affinity` to override, or `affinity: {}` to disable it.

`spec.netbox.config`

Field	Type	Default	Description
`allowedHosts`	[]string	`['*']`	Django allowed hosts
`metricsEnabled`	bool	`false`	Expose `/metrics` endpoint
`customPythonConfig`	string	-	Inline custom Python config
`customPythonConfigRef`	ConfigMapKeySelector	-	ConfigMap ref for Python config
`secretKey`	SecretKeySelector	Auto-generated	Django secret key
`emailPassword`	SecretKeySelector	-	Email password
`superuser`	object	Auto-generated	Superuser credentials. See `spec.netbox.config.superuser`.
`plugins`	object	`{}`	Custom plugins config for installing wheelhouse packages (Python wheels). See `spec.netbox.config.plugins`.
`postgres`	object	derived	PostgreSQL connection config. Derived from `spec.postgresql` when not set. See `spec.netbox.config.postgres`.
`redis`	object	derived	Redis connection config. Derived from `spec.redis` when not set. See `spec.netbox.config.redis`.
`storage.s3.enabled`	bool	`false`	Enable S3 media storage
`storage.s3.regionName`	string	`us-east-1`	AWS region name
`storage.s3.bucketName`	string	-	S3 bucket name
`storage.s3.endpointUrl`	string	-	S3 endpoint URL (for non-AWS S3-compatible storage)
`storage.s3.accessKeyId`	SecretKeySelector	-	Secret reference for the S3 access key ID
`storage.s3.secretAccessKey`	SecretKeySelector	-	Secret reference for the S3 secret access key
`storage.s3.tlsConfig`	object	-	S3 TLS/mTLS configuration (see S3 TLS)

S3 Storage TLS

The storage.s3.tlsConfig field uses the keychain TLS pattern for custom CA certificates and client certificates (mTLS):

Field	Type	Default	Description
`tlsConfig.insecureSkipVerify`	bool	`false`	Skip SSL certificate verification
`tlsConfig.keychainCaCertificates`	[]string	-	CA names from `tlsKeychain` for server verification
`tlsConfig.keychainClientCertificate`	string	-	Client cert name from `tlsKeychain` for mTLS

`spec.netbox.config.superuser`

Bring-your-own superuser credentials. When the section is omitted, the operator generates all credentials. When it is set, username, email, and password are required. apiToken is optional.

Each of the four fields is a SecretKeySelector with name, key, and optional.

Field	Type	Default	Description
`username`	SecretKeySelector	Required when set	Secret reference for the superuser name.
`email`	SecretKeySelector	Required when set	Secret reference for the superuser email address.
`password`	SecretKeySelector	Required when set	Secret reference for the superuser password.
`apiToken`	SecretKeySelector	-	Optional, and nothing reads its value. NetBox 4.5 and later issue peppered v2 tokens, which cannot be planted from a plaintext secret, so the bootstrap seeds no token. The field stays accepted so existing resources keep applying.

An apiToken key that does not exist stops NetBox from starting

apiToken is unread, and it is not harmless to set. Naming a key here adds it to the NetBox pod's projected secrets volume from a source that is not marked optional. If the Secret does not carry that key, kubelet fails the whole volume with MountVolume.SetUp failed for volume "secrets" : references non-existent secret key, and the NetBox pod never starts.

The name on apiToken is not consulted. The projected volume carries password and apiToken together, and it sources both from the Secret named by password.name. Point apiToken.key at a key that Secret really holds, or leave the field unset.

The operator reports this as SuperuserSecret=False, with a Warning event, so kubectl describe netboxenterprise names the key before you inspect the pod. See Status & Conditions.

`spec.netbox.config.plugins`

Custom Python plugin installation from a wheelhouse. Choose one wheelhouse source: s3 or pvc. See Custom Plugins for the full workflow.

Field	Type	Default	Description
`mediaWheelhousePollInterval`	string	runtime `5m`	How often the wheelhouse-watcher sidecar checks the media-directory wheelhouse file for a change in modification time or size. Accepts durations (`5m`, `1h`) or bare seconds (`300`). Applies only when no explicit wheelhouse source is set and a custom Python config is present.
`wheelhouse.s3.bucket`	string	-	Bucket holding the wheelhouse archive.
`wheelhouse.s3.key`	string	`media/wheelhouse.tar.gz`	Object key of the wheelhouse archive.
`wheelhouse.s3.endpoint`	string	-	S3 endpoint URL, for a non-AWS store.
`wheelhouse.s3.region`	string	-	S3 region name.
`wheelhouse.s3.verifySSL`	bool	`true`	Verify the S3 server certificate.
`wheelhouse.s3.credentialsSecret.name`	string	-	Secret holding the S3 credentials.
`wheelhouse.s3.credentialsSecret.accessKeyId`	string	-	Key within that Secret for the access key ID.
`wheelhouse.s3.credentialsSecret.secretAccessKey`	string	-	Key within that Secret for the secret access key.
`wheelhouse.pvc.claimName`	string	-	Existing PersistentVolumeClaim holding the wheelhouse.
`wheelhouse.pvc.create`	bool	`false`	Create the claim rather than adopt an existing one.
`wheelhouse.pvc.path`	string	`wheelhouse.tar.gz`	Path to the wheelhouse file within the volume.
`wheelhouse.pvc.size`	string	`1Gi`	Size of the claim. Read only when `create` is `true`.
`wheelhouse.pvc.storageClassName`	string	-	Storage class for the claim, when the operator creates it.

The operator reports an unreachable source as WheelhouseSourceProbe=False. It records the last-seen content fingerprint on status.wheelhouseFingerprint.

`spec.netbox.config.postgres`

NetBox's own PostgreSQL connection. The operator derives every field from spec.postgresql when the section is omitted, so set it only for an external database. Host, port, and TLS come from spec.postgresqlProfiles rather than from here.

Field	Type	Default	Description
`database`	string	`netbox`	Database name.
`user`	string	`netbox`	Database user.
`password`	SecretKeySelector	-	Secret reference for the database password.
`users`	[]object	operator-generated	Users for the operator to create in an internal PGO database. Each entry has `name`, `databases` (a list of database names), and `options` (raw PostgreSQL user options, such as `SUPERUSER`). Ignored for an external database.

`spec.netbox.config.redis`

NetBox's own Redis connection. The operator derives every field from spec.redis when the section is omitted.

Field	Type	Default	Description
`host`	string	derived	Redis hostname.
`port`	integer	`6379`	Redis port.
`username`	string	-	Redis ACL username (Redis 6.0 and later). An empty string falls back to legacy authentication.
`password`	SecretKeySelector	-	Secret reference for the Redis password.
`cachingDatabase`	integer	`1`	Redis DB index for the caching connection (0-65535). Set it to `0` for Redis Enterprise, which supports DB index 0 only.
`tasksDatabase`	integer	`0`	Redis DB index for the tasks (RQ) connection (0-65535). Redis Enterprise supports DB index 0 only.

`spec.postgresql`

Required. PostgreSQL database configuration.

Field	Type	Default	Description
`external`	bool	`false`	Use external PostgreSQL
`instances`	integer	`0`	PGO replica count (internal only). `0` auto-scales to `min(nodes, 3)`.
`version`	string	`18`	PostgreSQL major version
`storageSize`	string	`4Gi`	Storage per instance
`storageClassName`	string	-	Storage class
`registry`	string	-	Image registry override
`postgresqlProfile`	string	-	Name of a profile from `postgresqlProfiles` for host, port, and TLS config
`resources.cpu`	int	-	CPU request (millicores). Optional - when unset, no requests are applied
`resources.memory`	int	-	Memory request (MiB). Optional - when unset, no requests are applied
`limits.cpu`	int	-	CPU limit (millicores). Optional - when unset, no limits are applied
`limits.memory`	int	-	Memory limit (MiB). Optional - when unset, no limits are applied
`backups`	object	see below	pgBackRest backup configuration. See `spec.postgresql.backups`.

`spec.postgresql.backups`

New in 2.3.0. pgBackRest configuration for the built-in PostgreSQL. The defaults give a default install working disaster recovery with no configuration.

The whole section is ignored when spec.postgresql.external is true. An external database has no operator-managed repository, and its backups are yours to run.

postgresql:
  backups:
    enabled: true
    repoStorageSize: 16Gi
    retentionFull: 4
    fullSchedule: "0 1 * * 0"
    incrementalSchedule: "0 1 * * 1-6"

Field	Type	Default	Description
`enabled`	bool	`true`	Whether pgBackRest runs. Setting this to `false` leaves the database backed up by nothing at all -- read the warning below.
`repoStorageSize`	string	`16Gi`	Size of the pgBackRest repository PVC. Larger than the data volume default, because the repository holds a full backup set plus the WAL archived since it.
`repoStorageClassName`	string	-	Storage class for the repository PVC. Falls back to the PostgreSQL data storage class, then to the cluster default. It must not be a `hostPath` class: the repository is the only copy of your database in the Velero archive, and Velero cannot read a `hostPath` volume.
`retentionFull`	integer	`4`	Number of full backup sets pgBackRest keeps. Retention is by count, not by age: the repository PVC has a fixed size, so bounding the sets is what bounds the disk. Expiring a full backup also expires the incrementals and the WAL that depend on it.
`fullSchedule`	string	`0 1 * * 0`	Cron schedule for full backups. The default is Sundays at 01:00. An empty string disables scheduled full backups.
`incrementalSchedule`	string	`0 1 * * 1-6`	Cron schedule for incremental backups. The default is Monday to Saturday at 01:00, which skips the day the full backup runs. PGO refuses to overlap the two.

enabled: false opts out of PostgreSQL disaster recovery

Disabling pgBackRest removes the repository, and the PostgreSQL data volume stays excluded from Velero's filesystem backup. Nothing then backs the database up.

That exclusion is deliberate. A file-by-file copy of a live data directory is a torn copy, and a torn copy that looks restorable is worse than none. So this setting is an opt-out from PostgreSQL disaster recovery, not a choice of a different mechanism.

Disabling it on a running cluster is also not a clean revert. PGO leaves the repository StatefulSet and its PVC in place, and it pauses its own reconciliation of the cluster. The operator reports the pause as PostgresReconciliationPaused=True. Set backups back to enabled to resume.

Raising repoStorageSize is a PVC expansion, so it needs a storage class with allowVolumeExpansion. Embedded Cluster's local provisioner does not have it. Size retentionFull to fit the PVC rather than growing the PVC to fit retention.

See PostgreSQL Backups and Disaster Recovery for the repository layout, the verification commands, and the restore procedure.

`spec.storageBackend`

Where NetBox media and script files live.

Value	Description
`pvc`	Default. A node-local PersistentVolume. Cannot be shared across nodes, so it is single-node only.
`external`	An S3-compatible endpoint you provide. Configured under `spec.netbox.config`.
`in-cluster`	An object store the operator provisions and manages inside the cluster (Garage). Requires 3 or more nodes — below that, all three replicas can share a node and the operator reports `InClusterStorageBelowNodeGate`. See In-Cluster Object Storage.

spec:
  storageBackend: in-cluster

Multi-node deployments require external or in-cluster; a node-local volume pins NetBox to the node holding it. Changing this value does not migrate existing media — see Storage Migration.

`spec.redis`

Required. Redis cache/queue configuration.

Field	Type	Default	Description
`external`	bool	`false`	Use external Redis
`name`	string	`redis`	Instance name
`clusterSize`	integer	`0`	Redis replicas. `0` auto-scales based on node count (`min(nodes, 3)`) -- auto-scaling requires cluster-scoped RBAC. Sentinel is deployed automatically when the effective size is greater than 1.
`sentinelMasterName`	string	-	Sentinel master group name. Required when `sentinels` is set. Identifies which master group the Sentinels are monitoring (e.g. `netbox-redis`).
`sentinels`	[]object	-	Sentinel endpoints for external Redis HA. When set, NetBox uses Redis Sentinel for master discovery. Ignored for operator-managed Redis. See Redis Sentinels.
`persistence`	bool	`true`	Enable persistence
`requireAuth`	bool	`false`	Require authentication
`resources.cpu`	int	-	CPU request (millicores). Optional - when unset, no requests are applied
`resources.memory`	int	-	Memory request (MiB). Optional - when unset, no requests are applied
`limits.cpu`	int	-	CPU limit (millicores). Optional - when unset, no limits are applied
`limits.memory`	int	-	Memory limit (MiB). Optional - when unset, no limits are applied
`storageClassName`	string	-	Storage class
`storageSize`	string	`1Gi`	Storage size for Redis PVCs (when persistence is enabled)

The following tuning fields apply only to operator-managed Redis (external: false):

Field	Type	Default	Description
`aofEnabled`	bool	-	Enable AOF (append-only file) persistence. `false` avoids the OOM restart loop -- a restart does not replay the log to re-fill memory, and RDB snapshots still preserve the NetBox cache. `true` maximizes write durability. Omit to leave the Redis server default unchanged.
`maxMemoryPercent`	integer	-	Cap Redis memory at N% (0-100) of `limits.memory`, emitted as a `maxmemory` directive. No-op when `limits.memory` is unset.
`maxMemoryPolicy`	enum	-	Key eviction policy applied when `maxmemory` is reached: `noeviction`, `allkeys-lru`, `volatile-lru`, `allkeys-random`, `volatile-random`, `volatile-ttl`, `allkeys-lfu`, `volatile-lfu`. Without a policy, Redis defaults to `noeviction` (reject writes).
`dynamicConfig`	[]string	-	Extra Redis config directives appended to the managed ConfigMap. Applied on the next pod roll, not live. Prefer the typed fields above where they cover the need.
`additionalConfig`	string	-	Raw Redis config directives appended verbatim after the typed fields (Redis uses the last occurrence, so raw directives take precedence).

`spec.redis.sentinels[]`

Each entry is a Redis Sentinel endpoint address.

Field	Type	Default	Description
`host`	string	Required	Sentinel hostname
`port`	integer	`26379`	Sentinel port number

`spec.redis.tlsConfig`

Field	Type	Default	Description
`insecureSkipVerify`	bool	`false`	Skip TLS verification
`keychainCaCertificates`	[]string	-	CA names from `tlsKeychain`
`keychainClientCertificate`	string	-	Client cert name from `tlsKeychain`

`spec.copilot`

Optional. Private Copilot AI assistant backend. Requires a Private Copilot license entitlement and an LLM API key secret. Disabled by default.

copilot:
  enabled: true
  llmProvider: anthropic
  llmModel: anthropic/claude-sonnet-4-6
  llmApiKeySecret: copilot-llm-api-key
  llmApiKeySecretKey: apiKey

Field	Type	Default	Description
`enabled`	bool	`false`	Enable the Copilot backend and activate the `netbox_copilot` plugin in NetBox
`replicas`	integer	`1`	Copilot backend replicas
`llmProvider`	enum	`anthropic`	`anthropic` or `bedrock`
`llmModel`	string	`anthropic/claude-sonnet-4-6`	Provider-prefixed model identifier (e.g. `anthropic/claude-sonnet-4-6`, `bedrock/us.anthropic.claude-sonnet-4-6`)
`llmApiKeySecret`	string	`copilot-llm-api-key`	Kubernetes Secret holding the LLM API key (must exist in the same namespace)
`llmApiKeySecretKey`	string	`apiKey`	Key within `llmApiKeySecret`
`llmMaxSteps`	integer	`20`	Maximum LLM reasoning steps per conversation turn
`awsRegion`	string	`us-east-2`	AWS region for Bedrock. Sets `AWS_DEFAULT_REGION` in the Copilot container.
`awsCredentialsSecret`	string	-	Optional Secret with `aws_access_key_id` and `aws_secret_access_key` for Bedrock. Omit to use ambient credentials (IRSA, instance profile).
`databaseUser`	string	`copilot`	PostgreSQL user for the Copilot database
`redisDb`	integer	`2`	Redis database number (NetBox uses 0, Diode uses 1)
`netboxAuthCookieName`	string	`sessionid`	NetBox session cookie name used for authentication
`netboxAuthCacheTtl`	integer	`60`	TTL in seconds for caching NetBox auth session validation
`netboxAuthApiTimeout`	integer	`5`	Timeout in seconds for NetBox auth API calls
`resources.cpu`	int	`100`	CPU request (millicores)
`resources.memory`	int	`256`	Memory request (MiB)
`limits.cpu`	int	`1000`	CPU limit (millicores)
`limits.memory`	int	`1024`	Memory limit (MiB)
`image`	object	-	Image override for the Copilot backend. Same shape as `spec.netbox.image`: `registry`, `repository`, `tag`, `digest`, `pullPolicy`, and `imagePullSecrets`.
`timeouts`	object	-	Per-service timeout overrides for the Copilot Ingress and HTTPRoute. Same shape as `spec.netbox.timeouts`. When unset, Copilot falls back to long-lived-connection defaults, which suit a streaming chat response.
`topologySpreadConstraints`	[]TopologySpreadConstraint	-	Pod spread constraints for the Copilot pods. Replaces `spec.replication.topologySpreadConstraints` for this workload.

`spec.copilot.postgres`

Optional external PostgreSQL connection for Copilot. When omitted, Copilot uses the PGO-managed secret {cluster-name}-postgres-pguser-copilot.

copilot:
  postgres:
    databaseUrl:
      name: copilot-postgres-url
      key: DATABASE_URL
    sslMode: verify-full
    keychainCaCertificates:
      - copilot-db-ca

Field	Type	Default	Description
`databaseUrl.name`	string	Required	Secret name containing the full `DATABASE_URL` URI
`databaseUrl.key`	string	Required	Key within the secret (e.g. `DATABASE_URL`)
`sslMode`	enum	-	`disable`, `allow`, `prefer`, `require`, `verify-ca`, `verify-full`
`keychainCaCertificates`	[]string	-	CA names from `tlsKeychain` for verifying the Copilot PostgreSQL server. Required when `sslMode` is `verify-ca` or `verify-full`.
`keychainClientCertificate`	string	-	Client certificate name from `tlsKeychain`, for a server that demands mutual TLS (`clientcert=verify-ca` or `verify-full` in its `pg_hba.conf`).

`spec.diode`

Optional. Diode data ingestion pipeline.

Field	Type	Default	Description
`enabled`	bool	`true`	Enable Diode
`reconciler.replicas`	integer	`1`	Reconciler replicas
`ingester.replicas`	integer	`1`	Ingester replicas
`auth.replicas`	integer	`1`	Auth replicas
`hydra.replicas`	integer	`1`	Hydra replicas
`hydra.autoMigrate`	bool	`true`	Auto-run Hydra DB migrations
`hydra.postgresqlProfile`	string	-	PostgreSQL profile for Hydra's database connection
`hydra.databaseName`	string	`hydra`	PostgreSQL database name for Hydra
`hydra.databaseUser`	string	`hydra`	PostgreSQL database user for Hydra
`timeouts`	object	-	Per-route timeout overrides for the Diode surfaces. See `spec.diode.timeouts`.
`topologySpreadConstraints`	[]TopologySpreadConstraint	-	Default pod spread constraints for every Diode component. Each component can override it with its own field.

Fields on every Diode component

reconciler, ingester, auth, and hydra share one workload shape.

Field	Type	Default	Description
`enabled`	bool	`true`	Whether the operator creates this component's Deployment.
`replicas`	integer	`1`	Replica count.
`port`	integer	component-specific	Service port. `hydra` uses `spec.diode.config.hydra.serve` instead.
`serviceAccount`	string	derived	Service account name. Auto-generated as `{cluster-name}-diode-{component}` when unset.
`resources.cpu` / `resources.memory`	int	component-specific	CPU request (millicores) and memory request (MiB).
`limits.cpu` / `limits.memory`	int	component-specific	CPU limit (millicores) and memory limit (MiB).
`annotations`	map[string]string	-	Extra annotations for this component's resources.
`labels`	map[string]string	-	Extra labels for this component's resources.
`extraEnvs`	[]EnvVar	-	Extra environment variables for this component's container.
`image`	object	-	Image override. Same shape as `spec.netbox.image`.
`topologySpreadConstraints`	[]TopologySpreadConstraint	-	Pod spread constraints for this component.

`spec.diode.timeouts`

Field	Type	Default	Description
`http.ingress.connect` / `http.ingress.read` / `http.ingress.send`	string	-	Ingress timeouts for the Diode HTTP route.
`http.gateway.request` / `http.gateway.backendRequest`	string	-	Gateway API timeouts for the Diode HTTP route.
`grpc.ingress.connect` / `grpc.ingress.read` / `grpc.ingress.send`	string	-	Ingress timeouts for the Diode gRPC route. The gRPC route has no Gateway API timeout fields.

Raising these also means raising the NetBox-side deadlines in spec.netbox.diodePlugin. Otherwise the app layer caps the higher ingress bound.

`spec.diode.hydra.secrets`

Secret references for Hydra. When the section is omitted, the operator generates the references from the PostgreSQL configuration. Each field is a SecretKeySelector with name, key, and optional.

Field	Type	Default	Description
`dsn`	SecretKeySelector	operator-generated	Hydra's database connection DSN.
`system`	SecretKeySelector	operator-generated	Hydra's system secret, which encrypts stored tokens.
`cookie`	SecretKeySelector	operator-generated	Hydra's cookie secret, which signs session cookies.

`spec.diode.config.reconciler`

Field	Type	Default	Description
`autoApplyChangesets`	bool	`true`	Auto-apply change sets to NetBox. The operator sets this to `false` at runtime when Assurance is licensed; the schema default is `true`.
`logLevel`	enum	`INFO`	`INFO`, `DEBUG`, `WARN`, `ERROR`
`databaseName`	string	`diode`	PostgreSQL database
`databaseUser`	string	`diode`	PostgreSQL user
`migrationEnabled`	bool	`true`	Run DB migrations
`redisDb`	integer	`0`	Redis database number
`redisStreamDb`	integer	`1`	Redis stream database
`autoApplyProcessorConcurrency`	integer	`1`	Number of concurrent auto-apply processors (1-255).
`ingestionLogProcessorConcurrency`	integer	`4`	Number of concurrent ingestion-log processors (1-255).
`rateLimitRps`	integer	`20`	Rate limit (req/sec)
`rateLimitBurst`	integer	`1`	Burst allowance for the reconciler rate limiter
`rateLimitNetboxRps`	integer	`20`	Rate limit for requests against NetBox (req/sec)
`rateLimitNetboxBurst`	integer	`1`	Burst allowance for requests against NetBox
`netboxClientId`	string	`diode-to-netbox`	OAuth2 client ID the reconciler uses against NetBox
`pluginApiBaseUrl`	string	-	NetBox Diode plugin API base URL. Auto-generated from cluster name and namespace when unset.
`sentryDsn`	string	-	Sentry DSN for error tracking
`telemetryConfig`	object	-	OpenTelemetry config (see Telemetry config)
`postgres.postgresqlProfile`	string	-	PostgreSQL profile for Diode's database connection

`spec.diode.config.ingester` and `spec.diode.config.auth`

The ingester and auth components share the same logging, Sentry, and telemetry fields as the reconciler. The ingester additionally has its own Redis stream database.

Field	Type	Default	Description
`logLevel`	enum	`INFO`	`INFO`, `DEBUG`, `WARN`, `ERROR`
`sentryDsn`	string	-	Sentry DSN for error tracking
`telemetryConfig`	object	-	OpenTelemetry config (see Telemetry config)
`redisStreamDb` (ingester only)	integer	`1`	Redis stream database number
`redisMemoryHighWatermarkPct` (ingester only)	integer	`90`	Redis `used_memory`/`maxmemory` percentage at which the ingester rejects ingest with `ResourceExhausted` (0-100; `0` disables the check). Only meaningful when Redis has a `maxmemory` cap -- set `redis.maxMemoryPercent`.

Diode `telemetryConfig`

OpenTelemetry configuration shared by the reconciler, ingester, and auth components.

Field	Type	Default	Description
`metricsEnabled`	bool	`false`	Enable the Prometheus metrics endpoint
`metricsExporter`	enum	`prometheus`	`prometheus`, `otlp`, `console`, `none`
`metricsPort`	integer	-	Port for the metrics endpoint (component-specific default)
`traceExporter`	enum	`none`	Trace exporter backend
`environment`	string	-	Deployment environment name. When unset, Diode uses its built-in default.

`spec.diode.config.hydra`

Runtime configuration for the bundled Hydra OIDC server. Every field has a working default, so set these only to fit Hydra into an existing environment.

Field	Type	Default	Description
`serve.public.host`	string	`0.0.0.0`	Bind address for the public API.
`serve.public.port`	integer	`4444`	Public API port.
`serve.admin.host`	string	`0.0.0.0`	Bind address for the admin API. Read the warning below before you change it.
`serve.admin.port`	integer	`4445`	Admin API port.
`serve.tls.allowTerminationFrom`	[]string	`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`	IPv4 CIDR ranges whose `X-Forwarded-Proto` and `X-Forwarded-For` headers Hydra trusts in place of the real connection. Widen it only to cover a proxy you operate. A range that includes a client lets that client claim any source address and claim that a plaintext request arrived over TLS.
`urls.self.issuer`	string	derived	OIDC issuer URL. Auto-generated from the cluster name and the namespace when unset.
`strategies.accessToken`	enum	`jwt`	Access token strategy: `jwt` (stateless) or `opaque` (stateful). A `jwt` token cannot be revoked before it expires, so `ttl.accessToken` is the exposure window for a leaked one. Choose `opaque` where you need revocation to take effect at once.
`strategies.jwt.scopeClaim`	enum	`both`	Format of the `scope` claim in a JWT: `list`, `string`, or `both`.
`ttl.accessToken`	string	`1h`	Access token lifetime.
`oidc.subjectIdentifiers.supportedTypes`	[]string	`['public']`	Subject identifier types Hydra advertises.

Never expose the Hydra admin API

The admin API creates, edits, and deletes OAuth2 clients, and it has no authentication of its own. Its only protection is that nothing outside the cluster can reach it.

Do not put it behind an Ingress, a Gateway route, a LoadBalancer Service, or a NodePort. Change serve.admin.host and serve.admin.port only to avoid a port collision inside the pod, never to widen where the API is reachable from.

`spec.changes`

Change Management plugin (netbox_changes) toggle. Enabled by default; only takes effect on an enterprise license. Toggling it triggers the operator to run the required migration.

Field	Type	Default	Description
`enabled`	bool	`true`	Enable or disable Change Management (the `netbox_changes` plugin). Requires an enterprise license to take effect.

`spec.turbobulk`

TurboBulk bulk data API plugin. The enabled lever defaults on but only activates on a Premium-tier license.

Field	Type	Default	Description
`enabled`	bool	`true`	Enable or disable the TurboBulk plugin (the user lever). Effective only on Premium-tier licenses.
`enableWrites`	bool	`false`	Enable the TurboBulk write APIs (bulk load / delete)

`spec.plugins`

Cross-service plugin enablement.

plugins:
  assetLifecycle:
    enabled: true

`spec.plugins.assetLifecycle`

Asset Lifecycle Management (netbox_asset_lifecycle). Requires a Premium-tier license and is disabled by default.

Field	Type	Default	Description
`enabled`	bool	`false`	Enable or disable the Asset Lifecycle plugin (the user lever). Effective only on Premium-tier licenses. Cannot be combined with `netbox_inventory` or `netbox_lifecycle`.

Toggling this field triggers the operator to run the required migration and restarts the NetBox pods. Disabling retains all Asset Lifecycle tables and data. See Asset Lifecycle Management.

`spec.plugins.ndx`

NetBox Data Exchange (netbox_ndx), the device-type catalog. Comes with all paid NetBox Enterprise licenses and is enabled by default. New in 2.3.0.

Field	Type	Default	Description
`enabled`	bool	`true`	Enable or disable the NDX plugin (the user lever). Effective only when the license carries the NDX entitlement — the operator activates NDX only when both hold, so on a license without it this field has no effect.

Because the default is true, this field is an opt-out: set it to false to keep NDX off on an entitled license. The API token comes from the license entitlement and has no field here. Enabling it without the entitlement is refused rather than applied — the operator reports NdxReady=False and leaves NetBox running, since the plugin cannot start without its token. Disabling retains all imported catalog data. See NetBox Data Exchange (NDX).

`spec.tlsKeychain`

Centralized TLS certificate management.

`spec.tlsKeychain.caCertificateSecrets[]`

Field	Type	Default	Description
`name`	string	Required	Logical name (referenced in `tlsConfig`)
`secret`	string	-	Kubernetes secret name. When omitted, defaults to the value of `name` at runtime.
`key`	string	`ca.crt`	Key within the secret

`spec.tlsKeychain.clientCertificateSecrets[]`

Field	Type	Default	Description
`name`	string	Required	Logical name
`secret`	string	-	Kubernetes secret name. When omitted, defaults to the value of `name` at runtime.
`certKey`	string	`tls.crt`	Key within the secret holding the client certificate
`privateKey`	string	`tls.key`	Key within the secret holding the private key

`spec.routing`

Selects the operator's north/south routing path: Gateway API or Ingress. The resolved mode determines which resources the operator emits -- Gateway API resources (Gateway, HTTPRoute, GRPCRoute) in gateway mode, Ingress objects in ingress mode.

routing:
  mode: auto

Field	Type	Default	Description
`mode`	enum	`auto`	`auto`, `gateway`, or `ingress`. `auto` resolves to gateway mode when `spec.gateway` is enabled and the Gateway API CRDs are installed, and to ingress mode otherwise. `gateway` and `ingress` pin the path explicitly.

The routing mode is the master switch; the per-path enabled flags (spec.gateway.enabled, spec.ingress.enabled) still apply. A pinned mode whose path is disabled (for example mode: gateway with spec.gateway.enabled: false) emits nothing and raises a RoutingModeMismatch warning event. In auto mode with spec.gateway enabled but the Gateway API unusable, the operator falls back to ingress mode and raises a GatewayUnavailable warning event.

Embedded Cluster installs pin mode: gateway and serve traffic through the bundled Traefik controller. Helm installs default to auto.

`spec.ingress`

Cluster-wide Ingress configuration, used when the routing mode resolves to ingress (see spec.routing). When omitted, the operator generates Ingress objects with the default nginx class and no extra annotations.

ingress:
  className: nginx
  timeouts:
    connect: 10s
    read: 60s
    send: 60s
  tls:
    - hosts: [netbox.example.com]
      secretName: netbox-tls

Field	Type	Default	Description
`enabled`	bool	`true`	Whether the operator creates Ingress objects. When `false`, existing Ingress objects are pruned by orphan cleanup.
`className`	string	`nginx`	Kubernetes Ingress class name. Maps to `spec.ingressClassName` on every generated Ingress.
`annotations`	map[string]string	-	Extra annotations merged onto every Ingress object. Values here override the hardcoded nginx-specific defaults when keys collide.
`tls`	[]IngressTLS	-	TLS termination entries. Each entry maps directly to a Kubernetes `IngressTLS` object. All unique hosts across entries are used to create `IngressRule` entries.
`timeouts.connect`	string	-	Time allowed to establish a TCP connection to the upstream. Kubernetes-style duration.
`timeouts.read`	string	-	Time between successive reads from the upstream response. Kubernetes-style duration.
`timeouts.send`	string	-	Time between successive writes to the upstream request. Kubernetes-style duration.

Proxy timeouts are translated to nginx annotations. Non-nginx Ingress classes log a warning and leave timeouts at the controller defaults. Per-service overrides on spec.copilot.timeouts.ingress, spec.diode.timeouts.http.ingress, and spec.diode.timeouts.grpc.ingress field-merge with the cluster-wide defaults.

`spec.gateway`

Optional Gateway API configuration, used when the routing mode resolves to gateway (see spec.routing). When omitted or enabled: false, no Gateway API resources are created.

gateway:
  enabled: true
  className: traefik
  listeners:
    - name: http
      port: 80
      protocol: HTTP

Field	Type	Default	Description
`enabled`	bool	`false`	Whether the operator creates Gateway API resources. Opt-in. When `true` and the routing mode resolves to gateway, the operator creates a `Gateway` plus the associated `HTTPRoute` and `GRPCRoute` objects.
`className`	string	`traefik`	`GatewayClass` name for the `Gateway` resource. The default matches the bundled Traefik controller; common values for other controllers: `envoy`, `cilium`, `istio`.
`annotations`	map[string]string	-	Extra annotations merged onto all Gateway API resources.
`listeners`	[]GatewayListener	-	Gateway listener definitions. Each entry maps to a `spec.listeners[]` entry on the upstream `Gateway` type. See Gateway listeners.
`timeouts`	object	-	Cluster-wide HTTPRoute timeout defaults (`request`, `backendRequest`) as Gateway API durations (e.g. `60s`, `1m30s`). Per-service overrides on `spec.copilot.timeouts.gateway` and `spec.diode.timeouts.http.gateway` field-merge with these defaults.
`maxRequestBodyBytes`	int	`26214400`	Maximum request body (file uploads) in bytes; larger requests are rejected with `413`. `0` disables the limit. Enforced through a Traefik `Middleware` attached to the NetBox, Copilot, and Diode HTTP routes, so it applies only to the bundled Traefik gateway class -- bring-your-own gateways configure this themselves.

`spec.gateway.listeners[]`

Each entry maps to a spec.listeners[] entry on the upstream Gateway API Gateway type.

Field	Type	Default	Description
`name`	string	Required	Listener name, unique within the Gateway
`port`	integer	Required	Port the listener binds to
`protocol`	string	Required	Listener protocol (e.g. `HTTP`, `HTTPS`)
`hostname`	string	-	Virtual hostname to match for protocol types that define this concept
`tls`	object	-	TLS configuration for the listener
`allowedRoutes`	object	-	Types of routes that may attach to the listener and the trusted namespaces they may come from

`spec.extraCaCertificates`

Additional CA certificates to trust system-wide. Added to the system trust store of all NetBox components, merged into every service-specific CA bundle (PostgreSQL, Redis), and set as REQUESTS_CA_BUNDLE so Python HTTP clients (e.g., webhooks, custom scripts) also trust these CAs.

extraCaCertificates:
  - name: internal-ca-secret
    key: ca.crt

Each entry is a Kubernetes SecretKeySelector.

Field	Type	Default	Description
`name`	string	Required	Name of the Secret holding the certificate.
`key`	string	Required	Key within that Secret.
`optional`	bool	`false`	Whether the Secret and its key may be absent.

A reference that does not resolve is reported as TlsCaTrust=False with reason CaSecretMissing.

`spec.extraManifests`

New in 2.3.0. Extra Kubernetes manifests to apply beside the managed workloads.

Each entry is a YAML string, and one entry may hold several documents separated by ---. The operator parses each document into a typed resource, runs it through the same mutation pipeline as the resources it builds itself (canonical labels, registry rewrites, pull secrets), and applies it with the managed workloads.

Ten kinds are supported: Deployment, Job, Secret, ConfigMap, Service, ServiceAccount, Ingress, Role, RoleBinding, and PersistentVolumeClaim. Any other kind is rejected at reconcile time.

Every resource lands in the cluster's own namespace. A metadata.namespace that names a different one is rejected.

This field carries the operator's permissions

The operator applies these manifests with its own service account, and Role and RoleBinding are among the supported kinds. Write access to the NetBoxEnterprise resource therefore grants what the operator can do in that namespace. Treat edit rights on the resource as equivalent to that, and keep them off anyone who should not hold it.

extraManifests:
  - |
    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: site-branding
    data:
      banner: "Production"

`spec.replicatedApp`

Replicated-specific tuning. These knobs only apply when NetBox Enterprise is installed through Replicated (Embedded Cluster or KOTS).

`spec.replicatedApp.licenseFallback`

Retry budget for fetching the license from the Replicated SDK at startup. When the SDK is unreachable, the operator retries within this budget.

Field	Type	Default	Description
`retryInterval`	string	runtime `5s`	Delay between retry attempts. Accepts Kubernetes-style durations (`5s`) or bare seconds (`5`).
`totalTimeout`	string	runtime `30s`	Total time budget for the retry loop. Accepts durations (`30s`, `1m`) or bare seconds (`30`).

From 2.3.0 the operator invents no license when the budget runs out. It serves the last good license from its cache Secret instead. With no cached license either, it blocks reconciliation and reports LicenseHealth=False with reason LicenseUnavailable. Cleanup on delete is never blocked. See License Information.

Next Steps

Status & Conditions - Understanding cluster health
Configuration - Helm values reference

On this page