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

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	uint16	—	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	uint8	1	Web application replicas (0–255)
httpPort	uint16	8080	HTTP port
statusPort	uint16	8081	Health check port
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)
registry	string	—	Container registry override
imagePullPolicy	string	IfNotPresent	Image pull policy
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	ghcr.io	Container registry
repository	string	netbox-community/netbox	Image repository
tag	string	Chart-dependent	Image tag
digest	string	—	Image digest for pinning
pullPolicy	string	IfNotPresent	Pull policy

spec.netbox.worker (Required)

Field	Type	Default	Description
replicas	uint8	1	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)
storage.s3.enabled	bool	false	Enable S3 media storage
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	uint8	1	PGO replica count (internal only)
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	uint8	1	Redis replicas. Set to 0 to auto-scale 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.
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)

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	uint8	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	uint8	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	uint8	2	Redis database number (NetBox uses 0, Diode uses 1)
netboxAuthCookieName	string	sessionid	NetBox session cookie name used for authentication
netboxAuthCacheTtl	uint16	60	TTL in seconds for caching NetBox auth session validation
netboxAuthApiTimeout	uint8	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	uint8	1	Reconciler replicas
ingester.replicas	uint8	1	Ingester replicas
auth.replicas	uint8	1	Auth replicas
hydra.replicas	uint8	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 (without Assurance), false (with Assurance)	Auto-apply change sets. Defaults based on Assurance license.
logLevel	enum	INFO	INFO, DEBUG, WARN, ERROR
databaseName	string	diode	PostgreSQL database
databaseUser	string	diode	PostgreSQL user
migrationEnabled	bool	true	Run DB migrations
redisDb	uint8	0	Redis database number
redisStreamDb	uint8	1	Redis stream database
rateLimitRps	uint8	20	Rate limit (req/sec)
postgres.postgresqlProfile	string	—	PostgreSQL profile for Diode's database connection

spec.tlsKeychain

Centralized TLS certificate management.

spec.tlsKeychain.caCertificateSecrets[]

Field	Type	Default	Description
name	string	Required	Logical name (referenced in tlsConfig)
secret	string	Same as name	Kubernetes secret name
key	string	ca.crt	Key within the secret

spec.tlsKeychain.clientCertificateSecrets[]

Field	Type	Default	Description
name	string	Required	Logical name
secret	string	Same as name	Kubernetes secret name
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.
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.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

Next Steps

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