NetBoxEnterprise CRD Reference

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
Version	v1alpha1
Kind	NetBoxEnterprise
Scope	Namespaced
Short name	nbe

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

Minimal Example

apiVersion: netboxlabs.com/v1alpha1
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/v1alpha1
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

  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.

note

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.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

note

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.
storageClassName	string	-	Storage class override
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

spec.netbox.image

Field	Type	Default	Description
registry	string	docker.io	Container registry
repository	string	netboxcommunity/netbox	Image repository
tag	string	v4.5.10	Image tag
digest	string	-	Image digest for pinning
pullPolicy	string	IfNotPresent	Pull policy

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 (Required)

Field	Type	Default	Description
replicas	integer	Required	Worker replicas
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)

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 (all 4 fields required if set)
plugins	object	{}	Custom plugins config for installing wheelhouse packages (Python wheels). Specify a wheelhouse source (s3 or pvc).
postgres	object	derived	PostgreSQL connection config. Derived from spec.postgresql when not set.
redis	object	derived	Redis connection config. Derived from spec.redis when not set.
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.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

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)

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.

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

Each component also has resources, limits, annotations, labels, extraEnvs, and image fields. Service account names are auto-generated from the cluster name (e.g., {name}-diode-ingester) unless explicitly overridden.

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.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	Certificate key
privateKey	string	tls.key	Private key

spec.ingress

Cluster-wide Ingress configuration. 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.

note

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. When omitted or enabled: false, no Gateway API resources are created. Can coexist with Ingress -- both can be enabled simultaneously.

gateway:
  enabled: true
  className: istio
  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, the operator creates a Gateway plus the associated HTTPRoute and GRPCRoute objects.
className	string	istio	GatewayClass name for the Gateway resource. Common values: istio, envoy, cilium.
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. Per-service overrides on spec.copilot.timeouts.gateway and spec.diode.timeouts.http.gateway field-merge with these defaults.

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

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 before proceeding with the default Community license.

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. Once exhausted, reconcile proceeds with the default Community license. Accepts durations (30s, 1m) or bare seconds (30).

Next Steps

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