Docs
HelmApi

NetBoxEnterprise CRD

Complete field reference for the NetBoxEnterprise custom resource definition

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:

FieldValue
Groupnetboxlabs.com
Versionsv1alpha2 (storage), v1alpha1 (served)
KindNetBoxEnterprise
ScopeNamespaced
Short namenbe

NetBox Enterprise 2.2.0 introduced the v1alpha2 schema as the storage version. The older v1alpha1 schema is still served in 2.4.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.4.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

FieldTypeDefaultDescription
annotationsmap[string]string-Annotations applied to all managed resources.
backupsboolfalseHas no effect in this release. The operator does not read this field, and it creates no Velero objects. On a Helm install, set disasterRecovery.createVeleroSpecs in the chart values to render them -- see Backups. PostgreSQL backups are controlled by spec.postgresql.backups.
changesobject-Change Management plugin. See spec.changes.
clusterDnsSuffixstring-Kubernetes cluster DNS suffix (defaults to cluster.local).
copilotobject-Private Copilot backend. See spec.copilot.
diodeobject-Diode data ingestion pipeline. See spec.diode.
extraCaCertificates[]object-Additional CA certificates to trust system-wide. See spec.extraCaCertificates[].
extraManifests[]string-Extra Kubernetes manifests to apply beside the managed workloads. See spec.extraManifests.
gatewayobject-Gateway API configuration. See spec.gateway.
imagePullPolicyenumIfNotPresentDefault image pull policy. Values: IfNotPresent, Always, Never.
imagePullSecrets[]string-Pull secrets for private registries.
ingressobject-Cluster-wide Ingress configuration. See spec.ingress.
labelsmap[string]string-Labels applied to all managed resources.
maintenanceModeboolfalseScale down all app components, keep databases running.
netboxobject-NetBox application deployment. See spec.netbox.
plugins.assetLifecycleobject-Asset Lifecycle Management plugin. See spec.plugins.assetLifecycle.
plugins.ndxobject-NetBox Data Exchange plugin. See spec.plugins.ndx.
postgresqlobject-PostgreSQL database. See spec.postgresql.
postgresqlProfilesmap[string]object-Named PostgreSQL connection profiles. See spec.postgresqlProfiles.
proxyobject-Egress proxy settings. See spec.proxy.
reconcileIntervalstringunset (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. Pattern: ^[0-9]+(\.[0-9]+)?(h|m|s|ms)?([0-9]+(m|s|ms)?)*$.
redisobject-Redis cache and queue. See spec.redis.
registrystring-Container registry host override for all images.
registryNamespacestring-Registry namespace for flat-namespace registries (e.g., airgap). When set alongside registry, repository paths are flattened to {namespace}/{basename}.
replicatedApp.licenseFallbackobject-Retry budget for fetching the license from the Replicated SDK. See spec.replicatedApp.licenseFallback.
replicationobject-Cluster-wide replication and placement. See spec.replication.
routingobject-North/south routing mode. See spec.routing.
secretChecksumDebouncestringunset (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. Pattern: ^[0-9]+(\.[0-9]+)?(h|m|s|ms)?([0-9]+(m|s|ms)?)*$.
storageBackendenumpvcWhere NetBox media and script files live. See spec.storageBackend. Values: pvc, external, in-cluster.
suspendboolfalsePause reconciliation - existing workloads keep running.
tlsKeychain.caCertificateSecrets[]object-CA certificates that tlsConfig blocks reference by name. See spec.tlsKeychain.caCertificateSecrets[].
tlsKeychain.clientCertificateSecrets[]object-Client certificates that tlsConfig blocks reference by name. See spec.tlsKeychain.clientCertificateSecrets[].
turbobulkobject-TurboBulk bulk data API plugin. See spec.turbobulk.

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.

FieldTypeDefaultDescription
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
FieldTypeDefaultDescription
httpProxystring-HTTP proxy URL (e.g. http://proxy.corp:3128).
httpsProxystring-HTTPS proxy URL. Used for license, S3, and external HTTPS egress.
noProxystring-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']
FieldTypeDefaultDescription
<name>.hoststring-PostgreSQL hostname.
<name>.portuint16-PostgreSQL port. Range: 0-65535.
<name>.tlsConfigobject-TLS configuration (see PostgreSQL TLS).
<name>.usernamestring-PostgreSQL username.

PostgreSQL Profile tlsConfig

FieldTypeDefaultDescription
insecureSkipVerifyboolfalseSkip TLS verification.
keychainCaCertificates[]string-CA names from tlsKeychain.
keychainClientCertificatestring-Client cert name from tlsKeychain.
sslmodeenumpreferlibpq SSL mode. Values: disable, allow, prefer, require, verify-ca, verify-full.

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.

FieldTypeDefaultDescription
appReadyTimeoutstring5mMaximum 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. Pattern: ^[0-9]+(\.[0-9]+)?(h|m|s|ms)?([0-9]+(m|s|ms)?)*$.
configobject-NetBox application configuration. See spec.netbox.config.
diodePluginobject-NetBox-side deadlines for outbound calls to Diode. See spec.netbox.diodePlugin.
env[]EnvVar-Environment variables.
httpPortuint168080HTTP port. Range: 0-65535.
imageobject-NetBox container image. See spec.netbox.image.
limits.cpuuint641000CPU limit (millicores). Range: at least 0. Required when limits is set.
limits.memoryuint641500Memory limit (MiB). Range: at least 0. Required when limits is set.
mediaStorageSizestring10GiMedia PVC size. Pattern: ^(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[kMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$.
migrationStatementTimeoutstring15mPer-statement timeout for index reconciliation. Prevents a single slow index creation from consuming the entire job deadline. Accepts durations or bare seconds. Pattern: ^[0-9]+(\.[0-9]+)?(h|m|s|ms)?([0-9]+(m|s|ms)?)*$.
migrationTimeoutstring1hMaximum time for the migration Job to run before Kubernetes terminates it. Accepts durations (1h, 30m) or bare seconds (3600). Pattern: ^[0-9]+(\.[0-9]+)?(h|m|s|ms)?([0-9]+(m|s|ms)?)*$.
replicasuint81Web application replicas. Range: 0-255.
resources.cpuuint64200CPU request (millicores). Range: at least 0. Required when resources is set.
resources.memoryuint64750Memory request (MiB). Range: at least 0. Required when resources is set.
scriptsStorageSizestring1GiScripts PVC size. Pattern: ^(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[kMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$.
statusPortuint16-Deprecated. Health check port. Ignored since granian in nbe-core 4.5.x. Range: 0-65535.
storageAccessModeenumReadWriteOnceAccess mode for the media and scripts PVCs. Use ReadWriteMany with an RWX-capable storageClassName to spread replicas > 1 across nodes, or move media to S3 via config.storage. Values: ReadWriteOnce, ReadOnlyMany, ReadWriteMany, ReadWriteOncePod, null.
storageClassNamestring-Storage class override.
timeoutsobject-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.
urls[]string-External URLs (configures ingress).
workerobject-Background task worker. See spec.netbox.worker.
yamlEnvstring-YAML string of env vars.

spec.netbox.image

FieldTypeDefaultDescription
digeststring-Image digest for pinning.
imagePullSecrets[]LocalObjectReference-Pull secrets for this image only. Adds to the cluster-wide spec.imagePullSecrets.
pullPolicyenumIfNotPresentPull policy. Values: IfNotPresent, Always, Never.
registrystringdocker.ioContainer registry.
repositorystringnetboxcommunity/netboxImage repository.
tagstringv4.6.8Image tag. The default tracks the NetBox version this release ships.

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.

FieldTypeDefaultDescription
gateway.backendRequeststring-Maximum time for one request attempt to the NetBox backend.
gateway.requeststring-Maximum time the gateway waits for a complete NetBox response. Gateway API duration, such as 60s or 1m30s.
ingress.connectstring-Time allowed to open a TCP connection to the NetBox pods. Pattern: ^[0-9]+(\.[0-9]+)?(h|m|s|ms)?([0-9]+(m|s|ms)?)*$.
ingress.readstring-Time between successive reads from the NetBox response. Pattern: ^[0-9]+(\.[0-9]+)?(h|m|s|ms)?([0-9]+(m|s|ms)?)*$.
ingress.sendstring-Time between successive writes to the NetBox request. Pattern: ^[0-9]+(\.[0-9]+)?(h|m|s|ms)?([0-9]+(m|s|ms)?)*$.

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.

FieldTypeDefaultDescription
authTimeoutstringruntime 500msTimeout for Hydra token introspection calls from the NetBox plugins. Pattern: ^[0-9]+(\.[0-9]+)?(h|m|s|ms)?([0-9]+(m|s|ms)?)*$.
grpcTimeoutstringruntime 5sTimeout for Diode gRPC calls from the NetBox plugins. Pattern: ^[0-9]+(\.[0-9]+)?(h|m|s|ms)?([0-9]+(m|s|ms)?)*$.

spec.netbox.worker

FieldTypeDefaultDescription
affinityAffinity-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.
env[]EnvVar-Environment variables for worker containers. Merged with yamlEnv.
limits.cpuuint641000CPU limit (millicores). Range: at least 0. Required when limits is set.
limits.memoryuint641500Memory limit (MiB). Range: at least 0. Required when limits is set.
replicasuint81Worker replicas (0-255). Operator-applied default when unset. Range: 0-255.
resources.cpuuint64100CPU request (millicores). Range: at least 0. Required when resources is set.
resources.memoryuint64128Memory request (MiB). Range: at least 0. Required when resources is set.
topologySpreadConstraints[]TopologySpreadConstraint-Pod spread constraints for the worker pods. Replaces spec.replication.topologySpreadConstraints for this workload.
yamlEnvstring-YAML string of env vars (e.g. "FOO: bar\nBAZ: qux").

spec.netbox.config

FieldTypeDefaultDescription
allowedHosts[]string['*']Django allowed hosts.
customPythonConfigstring-Inline custom Python config.
customPythonConfigRefConfigMapKeySelector-ConfigMap key with extra Python settings, mounted into every NetBox pod and into the migration Job. The operator does not watch the ConfigMap, so it sees an edit on its next periodic reconcile; it then runs database migrations again and restarts the NetBox pods. If the ConfigMap or the key is missing, new NetBox pods cannot start unless you set optional: true, in which case NetBox starts without the file.
emailPasswordSecretKeySelector-Email password.
metricsEnabledboolfalseExpose /metrics endpoint.
pluginsobject{}Custom plugins config for installing wheelhouse packages (Python wheels). See spec.netbox.config.plugins.
postgresobjectderivedPostgreSQL connection config. Derived from spec.postgresql when not set. See spec.netbox.config.postgres.
redisobjectderivedRedis connection config. Derived from spec.redis when not set. See spec.netbox.config.redis.
secretKeySecretKeySelectorAuto-generatedDjango secret key.
storage.s3.accessKeyIdSecretKeySelector-Secret reference for the S3 access key ID.
storage.s3.bucketNamestring-S3 bucket name.
storage.s3.enabledboolfalseEnable S3 media storage.
storage.s3.endpointUrlstring-S3 endpoint URL (for non-AWS S3-compatible storage).
storage.s3.regionNamestringus-east-1AWS region name.
storage.s3.secretAccessKeySecretKeySelector-Secret reference for the S3 secret access key.
storage.s3.tlsConfigobject-S3 TLS/mTLS configuration (see S3 TLS).
superuserobjectAuto-generatedSuperuser credentials. See spec.netbox.config.superuser.

S3 Storage TLS

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

FieldTypeDefaultDescription
insecureSkipVerifyboolfalseSkip SSL certificate verification.
keychainCaCertificates[]string-CA names from tlsKeychain for server verification.
keychainClientCertificatestring-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.

FieldTypeDefaultDescription
apiTokenSecretKeySelector-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.
emailSecretKeySelectorRequiredSecret reference for the superuser email address.
passwordSecretKeySelectorRequiredSecret reference for the superuser password.
usernameSecretKeySelectorRequiredSecret reference for the superuser name.

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.

FieldTypeDefaultDescription
mediaWheelhousePollIntervalstringruntime 5mHow 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. Pattern: ^[0-9]+(\.[0-9]+)?(h|m|s|ms)?([0-9]+(m|s|ms)?)*$.
wheelhouse.pvc.claimNamestring-Existing PersistentVolumeClaim holding the wheelhouse. Required when wheelhouse.pvc is set.
wheelhouse.pvc.createboolfalseCreate the claim rather than adopt an existing one.
wheelhouse.pvc.pathstringwheelhouse.tar.gzPath to the wheelhouse file within the volume.
wheelhouse.pvc.sizestring1GiSize of the claim. Read only when create is true. Pattern: ^(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[kMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$.
wheelhouse.pvc.storageClassNamestring-Storage class for the claim, when the operator creates it.
wheelhouse.s3.bucketstring-Bucket holding the wheelhouse archive. Required when wheelhouse.s3 is set.
wheelhouse.s3.credentialsSecret.accessKeyIdstring-Key within that Secret for the access key ID.
wheelhouse.s3.credentialsSecret.namestring-Secret holding the S3 credentials. Required when wheelhouse.s3 is set.
wheelhouse.s3.credentialsSecret.secretAccessKeystring-Key within that Secret for the secret access key.
wheelhouse.s3.endpointstring-S3 endpoint URL, for a non-AWS store.
wheelhouse.s3.keystringmedia/wheelhouse.tar.gzObject key of the wheelhouse archive.
wheelhouse.s3.regionstring-S3 region name.
wheelhouse.s3.verifySSLbooltrueVerify the S3 server certificate.

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.

FieldTypeDefaultDescription
databasestringnetboxDatabase name. Length: 1-63.
passwordSecretKeySelector-Secret reference for the database password.
userstringnetboxDatabase user. Length: 1-63.
users[].databases[]stringRequiredDatabases the user owns. Each entry: Length: 1-63.
users[].namestringRequiredPostgreSQL user name. Length: 1-63.
users[].optionsstringRequiredRaw PostgreSQL user options, such as SUPERUSER.

spec.netbox.config.redis

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

FieldTypeDefaultDescription
cachingDatabaseuint161Redis DB index for the caching connection (0-65535). Set it to 0 for Redis Enterprise, which supports DB index 0 only. Range: 0-65535.
hoststringRequiredRedis hostname.
passwordSecretKeySelector-Secret reference for the Redis password.
portuint166379Redis port. Range: 0-65535.
tasksDatabaseuint160Redis DB index for the tasks (RQ) connection (0-65535). Redis Enterprise supports DB index 0 only. Range: 0-65535.
usernamestring-Redis ACL username (Redis 6.0 and later). An empty string falls back to legacy authentication.

spec.postgresql

Required. PostgreSQL database configuration.

FieldTypeDefaultDescription
backupsobjectsee belowpgBackRest backup configuration. See spec.postgresql.backups.
externalboolfalseUse external PostgreSQL.
instancesuint80PGO replica count (internal only). 0 auto-scales to min(nodes, 3). Range: 0-255.
limits.cpuuint64-CPU limit (millicores). Optional - when unset, no limits are applied. Range: at least 0. Required when limits is set.
limits.memoryuint64-Memory limit (MiB). Optional - when unset, no limits are applied. Range: at least 0. Required when limits is set.
postgresqlProfilestring-Name of a profile from postgresqlProfiles for host, port, and TLS config.
registrystring-Image registry override.
resources.cpuuint64-CPU request (millicores). Optional - when unset, no requests are applied. Range: at least 0. Required when resources is set.
resources.memoryuint64-Memory request (MiB). Optional - when unset, no requests are applied. Range: at least 0. Required when resources is set.
storageClassNamestring-Storage class.
storageSizestring4GiStorage per instance. Pattern: ^(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[kMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$.
versionstring18PostgreSQL major version.

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"
FieldTypeDefaultDescription
enabledbooltrueWhether pgBackRest runs. Setting this to false leaves the database backed up by nothing at all -- read the warning below.
fullSchedulestring0 1 * * 0Cron schedule for full backups. The default is Sundays at 01:00. In 2.4.0, an empty string fails validation, so you cannot turn off scheduled full backups. On a busy database, more frequent full backups use less repository disk, because less WAL is kept between them. Do not schedule a full backup at a time incrementalSchedule also runs: PGO does not run two backups at once. On an admin console install, set it with Full Backup Schedule in the PostgreSQL group.
incrementalSchedulestring0 1 * * 1-6Cron 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.
repoStorageClassNamestring-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.
repoStorageSizestring16GiSize 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. The PostgresBackupRepoPressure condition turns True when the repository grows past this size or its filesystem is 70% full. On Embedded Cluster the storage class cannot expand a volume, so a larger value on an existing install fails the reconcile: lower retentionFull instead. Pattern: ^(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[kMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$.
retentionFulluint84Number 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. After a disaster-recovery restore, the restored cluster's own backups take slots too, so a low value soon expires the backup you restored from. On an admin console install, set it with Full Backups to Keep in the PostgreSQL group. Range: 1-255.

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.

ValueDescription
pvcDefault. A node-local PersistentVolume. Cannot be shared across nodes, so it is single-node only.
externalAn S3-compatible endpoint you provide. Configured under spec.netbox.config.
in-clusterAn 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.

FieldTypeDefaultDescription
additionalConfigstring-Operator-managed Redis only. Raw Redis config directives appended verbatim after the typed fields (Redis uses the last occurrence, so raw directives take precedence).
aofEnabledbool-Operator-managed Redis only. 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.
clusterSizeuint80Redis 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. Range: 0-255.
dynamicConfig[]string-Operator-managed Redis only. Extra Redis config directives appended to the managed ConfigMap. Applied on the next pod roll, not live. Prefer the typed fields where they cover the need.
externalboolfalseUse external Redis.
limits.cpuuint64-CPU limit (millicores). Optional - when unset, no limits are applied. Range: at least 0. Required when limits is set.
limits.memoryuint64-Memory limit (MiB). Optional - when unset, no limits are applied. Range: at least 0. Required when limits is set.
maxMemoryPercentuint8-Operator-managed Redis only. Cap Redis memory at N% of limits.memory, emitted as a maxmemory directive. No-op when limits.memory is unset. Range: 0-100.
maxMemoryPolicyenum-Operator-managed Redis only. Key eviction policy applied when maxmemory is reached. Without a policy, Redis defaults to noeviction (reject writes). Values: noeviction, allkeys-lru, volatile-lru, allkeys-random, volatile-random, volatile-ttl, allkeys-lfu, volatile-lfu.
namestringredisInstance name.
persistencebooltrueEnable persistence.
requireAuthboolfalseRequire authentication.
resources.cpuuint64-CPU request (millicores). Optional - when unset, no requests are applied. Range: at least 0. Required when resources is set.
resources.memoryuint64-Memory request (MiB). Optional - when unset, no requests are applied. Range: at least 0. Required when resources is set.
sentinelMasterNamestring-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.
storageClassNamestring-Storage class.
storageSizestring1GiStorage size for Redis PVCs (when persistence is enabled). Pattern: ^(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[kMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$.
tlsConfigobject-TLS configuration for the Redis connection. See spec.redis.tlsConfig.

spec.redis.sentinels[]

Each entry is a Redis Sentinel endpoint address.

FieldTypeDefaultDescription
hoststringRequiredSentinel hostname.
portuint1626379Sentinel port number. Range: 0-65535.

spec.redis.tlsConfig

FieldTypeDefaultDescription
insecureSkipVerifyboolfalseSkip TLS verification.
keychainCaCertificates[]string-CA names from tlsKeychain.
keychainClientCertificatestring-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
FieldTypeDefaultDescription
awsCredentialsSecretstring-Optional Secret with aws_access_key_id and aws_secret_access_key for Bedrock. Omit to use ambient credentials (IRSA, instance profile).
awsRegionstringus-east-2AWS region for Bedrock. Sets AWS_DEFAULT_REGION in the Copilot container.
databaseUserstringcopilotPostgreSQL user for the Copilot database. Length: 1-63.
enabledboolfalseEnable the Copilot backend and activate the netbox_copilot plugin in NetBox.
imageobject-Image override for the Copilot backend. Same shape as spec.netbox.image: registry, repository, tag, digest, pullPolicy, and imagePullSecrets.
limits.cpuuint641000CPU limit (millicores). Range: at least 0. Required when limits is set.
limits.memoryuint641024Memory limit (MiB). Range: at least 0. Required when limits is set.
llmApiKeySecretstringcopilot-llm-api-keyKubernetes Secret holding the LLM API key (must exist in the same namespace).
llmApiKeySecretKeystringapiKeyKey within llmApiKeySecret.
llmMaxStepsuint820Maximum LLM reasoning steps per conversation turn. Range: 0-255.
llmModelstringanthropic/claude-sonnet-4-6Provider-prefixed model identifier (e.g. anthropic/claude-sonnet-4-6, bedrock/us.anthropic.claude-sonnet-4-6).
llmProviderenumanthropicLLM provider. Values: anthropic, bedrock.
netboxAuthApiTimeoutuint85Timeout in seconds for NetBox auth API calls. Range: 0-255.
netboxAuthCacheTtluint1660TTL in seconds for caching NetBox auth session validation. Range: 0-65535.
netboxAuthCookieNamestringsessionidNetBox session cookie name used for authentication.
postgresobject-External PostgreSQL connection for Copilot. See spec.copilot.postgres.
redisDbuint82Redis database number (NetBox uses 0, Diode uses 1). Range: 0-255.
replicasuint81Copilot backend replicas. Range: 0-255.
resources.cpuuint64100CPU request (millicores). Range: at least 0. Required when resources is set.
resources.memoryuint64256Memory request (MiB). Range: at least 0. Required when resources is set.
timeoutsobject-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
FieldTypeDefaultDescription
databaseUrlSecretKeySelectorRequiredSecret key that holds the full DATABASE_URL URI.
keychainCaCertificates[]string-CA names from tlsKeychain for verifying the Copilot PostgreSQL server. Required when sslMode is verify-ca or verify-full.
keychainClientCertificatestring-Client certificate name from tlsKeychain, for a server that demands mutual TLS (clientcert=verify-ca or verify-full in its pg_hba.conf).
sslModeenum-libpq SSL mode for the Copilot database connection. Values: disable, allow, prefer, require, verify-ca, verify-full.

spec.diode

Optional. Diode data ingestion pipeline.

FieldTypeDefaultDescription
authobject-Auth component. See spec.diode.<component>.
config.authobject-Auth runtime configuration. See spec.diode.config.<component>.
config.hydraobject-Hydra runtime configuration. See spec.diode.config.hydra.
config.ingesterobject-Ingester runtime configuration. See spec.diode.config.<component>.
config.reconcilerobject-Reconciler runtime configuration. See spec.diode.config.reconciler.
enabledbooltrueEnable Diode.
hydraobject-Hydra OIDC server component. See spec.diode.<component>.
ingesterobject-Ingester component. See spec.diode.<component>.
reconcilerobject-Reconciler component. See spec.diode.<component>.
timeoutsobject-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.

FieldTypeDefaultDescription
annotationsmap[string]string-Extra annotations for this component's resources.
enabledbooltrueWhether the operator creates this component's Deployment.
extraEnvs[]EnvVar-Extra environment variables for this component's container.
imageobject-Image override. Same shape as spec.netbox.image.
labelsmap[string]string-Extra labels for this component's resources.
limits.cpuuint64component-specificCPU limit (millicores). Range: at least 0. Required when limits is set.
limits.memoryuint64component-specificMemory limit (MiB). Range: at least 0. Required when limits is set.
portuint16component-specificService port. hydra uses spec.diode.config.hydra.serve instead. Range: 0-65535. Not on hydra.
replicasuint81Replica count. Range: 0-255.
resources.cpuuint64component-specificCPU request (millicores). Range: at least 0. Required when resources is set.
resources.memoryuint64component-specificMemory request (MiB). Range: at least 0. Required when resources is set.
serviceAccountstringderivedService account name. Auto-generated as {cluster-name}-diode-{component} when unset.
topologySpreadConstraints[]TopologySpreadConstraint-Pod spread constraints for this component.
autoMigratebooltrueRun the Hydra database migrations automatically. Only on hydra.
databaseNamestringhydraPostgreSQL database name for Hydra. Length: 1-63. Only on hydra.
databaseUserstringhydraPostgreSQL database user for Hydra. Length: 1-63. Only on hydra.
postgresqlProfilestring-PostgreSQL profile for the Hydra database connection. Only on hydra.
secretsobject-Secret references for Hydra. See spec.diode.hydra.secrets. Only on hydra.

spec.diode.timeouts

FieldTypeDefaultDescription
grpc.ingress.connectstring-Time allowed to open a TCP connection for the Diode gRPC route. The gRPC route has no Gateway API timeout fields. Pattern: ^[0-9]+(\.[0-9]+)?(h|m|s|ms)?([0-9]+(m|s|ms)?)*$.
grpc.ingress.readstring-Time between successive reads for the Diode gRPC route. Pattern: ^[0-9]+(\.[0-9]+)?(h|m|s|ms)?([0-9]+(m|s|ms)?)*$.
grpc.ingress.sendstring-Time between successive writes for the Diode gRPC route. Pattern: ^[0-9]+(\.[0-9]+)?(h|m|s|ms)?([0-9]+(m|s|ms)?)*$.
httpobject-Ingress and Gateway API timeouts for the Diode HTTP route. Same shape as spec.netbox.timeouts.

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.

FieldTypeDefaultDescription
cookieSecretKeySelectoroperator-generatedHydra's cookie secret, which signs session cookies.
dsnSecretKeySelectoroperator-generatedHydra's database connection DSN.
systemSecretKeySelectoroperator-generatedHydra's system secret, which encrypts stored tokens.

spec.diode.config.reconciler

FieldTypeDefaultDescription
autoApplyChangesetsbooltrueAuto-apply change sets to NetBox. The operator sets this to false at runtime when Assurance is licensed; the schema default is true.
autoApplyProcessorConcurrencyuint81Number of concurrent auto-apply processors (1-255). Range: 1-255.
databaseNamestringdiodePostgreSQL database. Length: 1-63.
databaseUserstringdiodePostgreSQL user. Length: 1-63.
ingestionLogProcessorConcurrencyuint84Number of concurrent ingestion-log processors (1-255). Range: 1-255.
logLevelenumINFOLog level. Values: INFO, DEBUG, WARN, ERROR.
migrationEnabledbooltrueRun DB migrations.
netboxClientIdstringdiode-to-netboxOAuth2 client ID the reconciler uses against NetBox.
pluginApiBaseUrlstring-NetBox Diode plugin API base URL. Auto-generated from cluster name and namespace when unset.
postgres.passwordSecretKeySelector-Secret reference for the Diode database password. Required when postgres is set.
postgres.postgresqlProfilestring-PostgreSQL profile for Diode's database connection.
rateLimitBurstuint81Burst allowance for the reconciler rate limiter. Range: 0-255.
rateLimitNetboxBurstuint81Burst allowance for requests against NetBox. Range: 0-255.
rateLimitNetboxRpsuint820Rate limit for requests against NetBox (req/sec). Range: 0-255.
rateLimitRpsuint820Rate limit (req/sec). Range: 0-255.
redisDbuint80Redis database number. Range: 0-255.
redisStreamDbuint81Redis stream database. Range: 0-255.
sentryDsnstring-Sentry DSN for error tracking.
telemetryConfigobject-OpenTelemetry config (see Telemetry config).

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.

FieldTypeDefaultDescription
logLevelenumINFOLog level. Values: INFO, DEBUG, WARN, ERROR.
redisMemoryHighWatermarkPctuint890Redis 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. Range: 0-100. Only on ingester.
redisStreamDbuint81Redis stream database number. Range: 0-255. Only on ingester.
sentryDsnstring-Sentry DSN for error tracking.
telemetryConfigobject-OpenTelemetry config (see Telemetry config).

Diode telemetryConfig

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

FieldTypeDefaultDescription
environmentstring-Deployment environment name. When unset, Diode uses its built-in default.
metricsEnabledboolfalseEnable the Prometheus metrics endpoint.
metricsExporterenumprometheusMetrics exporter backend. Values: prometheus, otlp, console, none.
metricsPortuint16-Port for the metrics endpoint (component-specific default). Range: 0-65535.
traceExporterenumnoneTrace exporter backend. Values: otlp, console, none.

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.

FieldTypeDefaultDescription
oidc.subjectIdentifiers.supportedTypes[]enum['public']Subject identifier types Hydra advertises. Values: public, pairwise. Required when oidc is set.
serve.admin.hoststring0.0.0.0Bind address for the admin API. Read the warning below before you change it.
serve.admin.portuint164445Admin API port. Range: 0-65535.
serve.public.hoststring0.0.0.0Bind address for the public API.
serve.public.portuint164444Public API port. Range: 0-65535.
serve.tls.allowTerminationFrom[]string10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16IPv4 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. Each entry: Pattern: ^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\/(3[0-2]|[0-2]?[0-9])$.
strategies.accessTokenenumjwtAccess 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. Values: jwt, opaque. Required when strategies is set.
strategies.jwt.scopeClaimenumbothFormat of the scope claim in a JWT. Values: list, string, both. Required when strategies is set.
ttl.accessTokenstring1hAccess token lifetime.
urls.self.issuerstringderivedOIDC issuer URL. Auto-generated from the cluster name and the namespace when unset.

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.

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

FieldTypeDefaultDescription
enableWritesboolfalseEnable the TurboBulk write APIs (bulk load / delete).
enabledbooltrueEnable or disable the TurboBulk plugin (the user lever). Effective only on Premium-tier licenses.

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.

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

FieldTypeDefaultDescription
enabledbooltrueEnable 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[]

FieldTypeDefaultDescription
keystringca.crtKey within the secret.
namestringRequiredLogical name (referenced in tlsConfig).
secretstring-Kubernetes secret name. When omitted, defaults to the value of name at runtime.

spec.tlsKeychain.clientCertificateSecrets[]

FieldTypeDefaultDescription
certKeystringtls.crtKey within the secret holding the client certificate.
namestringRequiredLogical name.
privateKeystringtls.keyKey within the secret holding the private key.
secretstring-Kubernetes secret name. When omitted, defaults to the value of name at runtime.

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
FieldTypeDefaultDescription
modeenumautoauto 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. Values: auto, gateway, ingress.

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
FieldTypeDefaultDescription
annotationsmap[string]string-Extra annotations merged onto every Ingress object. Values here override the hardcoded nginx-specific defaults when keys collide.
classNamestringnginxKubernetes Ingress class, set as spec.ingressClassName on every Ingress the operator creates. The Diode and Copilot Ingresses depend on the path rewrite that the operator sets only for the nginx class: on any other class it does not create them, deletes those it created before, and logs a warning, but it still creates the NetBox Ingress. To route Diode and Copilot through another controller, set routing.mode: gateway and gateway.enabled: true.
enabledbooltrueWhether the operator creates Ingress objects. When false, existing Ingress objects are pruned by orphan cleanup.
timeouts.connectstring-Time allowed to establish a TCP connection to the upstream. Kubernetes-style duration. Pattern: ^[0-9]+(\.[0-9]+)?(h|m|s|ms)?([0-9]+(m|s|ms)?)*$.
timeouts.readstring-Time between successive reads from the upstream response. Kubernetes-style duration. Pattern: ^[0-9]+(\.[0-9]+)?(h|m|s|ms)?([0-9]+(m|s|ms)?)*$.
timeouts.sendstring-Time between successive writes to the upstream request. Kubernetes-style duration. Pattern: ^[0-9]+(\.[0-9]+)?(h|m|s|ms)?([0-9]+(m|s|ms)?)*$.
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.

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
FieldTypeDefaultDescription
annotationsmap[string]string-Extra annotations merged onto all Gateway API resources.
classNamestringtraefikGatewayClass name for the Gateway resource. The default matches the bundled Traefik controller; common values for other controllers: envoy, cilium, istio.
enabledboolfalseWhether 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.
listeners[]object-Gateway listener definitions. Each entry maps to a spec.listeners[] entry on the upstream Gateway type. See Gateway listeners.
maxRequestBodyBytesint6426214400Maximum 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.
timeouts.backendRequeststring-Cluster-wide default for the maximum time of one request attempt to a backend. Gateway API duration.
timeouts.requeststring-Cluster-wide default for the maximum time the gateway waits for a complete response. Gateway API duration, such as 60s or 1m30s. Per-service overrides on spec.netbox.timeouts.gateway, spec.copilot.timeouts.gateway, and spec.diode.timeouts.http.gateway field-merge with it.

spec.gateway.listeners[]

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

FieldTypeDefaultDescription
allowedRoutesAllowedRoutes-Types of routes that may attach to the listener and the trusted namespaces they may come from.
hostnamestring-Virtual hostname to match for protocol types that define this concept.
namestringRequiredListener name, unique within the Gateway.
portint32RequiredPort the listener binds to.
protocolstringRequiredListener protocol (e.g. HTTP, HTTPS).
tlsGatewayTLSConfig-TLS configuration for the listener.

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.

FieldTypeDefaultDescription
keystringRequiredKey within that Secret.
namestringRequiredName of the Secret holding the certificate.
optionalboolfalseWhether 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.

FieldTypeDefaultDescription
retryIntervalstringruntime 5sDelay between retry attempts. Accepts Kubernetes-style durations (5s) or bare seconds (5). Pattern: ^[0-9]+(\.[0-9]+)?(h|m|s|ms)?([0-9]+(m|s|ms)?)*$.
totalTimeoutstringruntime 30sTotal time budget for the retry loop. Accepts durations (30s, 1m) or bare seconds (30). Pattern: ^[0-9]+(\.[0-9]+)?(h|m|s|ms)?([0-9]+(m|s|ms)?)*$.

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

Topology-Aware Node Labels

Tag Embedded Cluster nodes with topology labels (topology.kubernetes.io/zone) to enable zone-aware pod spreading and storage replication

Status & Conditions

NetBoxEnterprise status fields, condition types, and component health reference

On this page

Minimal ExampleFull ExampleSpec ReferenceTop-Level Fieldsspec.replicationspec.proxyspec.postgresqlProfilesPostgreSQL Profile tlsConfigspec.netboxspec.netbox.imagespec.netbox.timeoutsspec.netbox.diodePluginspec.netbox.workerspec.netbox.configS3 Storage TLSspec.netbox.config.superuserspec.netbox.config.pluginsspec.netbox.config.postgresspec.netbox.config.redisspec.postgresqlspec.postgresql.backupsspec.storageBackendspec.redisspec.redis.sentinels[]spec.redis.tlsConfigspec.copilotspec.copilot.postgresspec.diodeFields on every Diode componentspec.diode.timeoutsspec.diode.hydra.secretsspec.diode.config.reconcilerspec.diode.config.ingester and spec.diode.config.authDiode telemetryConfigspec.diode.config.hydraspec.changesspec.turbobulkspec.pluginsspec.plugins.assetLifecyclespec.plugins.ndxspec.tlsKeychainspec.tlsKeychain.caCertificateSecrets[]spec.tlsKeychain.clientCertificateSecrets[]spec.routingspec.ingressspec.gatewayspec.gateway.listeners[]spec.extraCaCertificatesspec.extraManifestsspec.replicatedAppspec.replicatedApp.licenseFallbackNext Steps