Docs
HelmConfiguration

Diode Configuration

Configure the Diode data ingestion pipeline for NetBox Enterprise

Diode provides automated data ingestion into NetBox. It consists of four components:

  • Reconciler - Processes change sets and updates NetBox via API
  • Ingester - Receives incoming data and writes to Redis streams
  • Auth - Authentication service for Diode API clients
  • Hydra - Ory Hydra OAuth2/OIDC server for token management

Enable/Disable Diode

KeyTypeDefaultDescription
diode.enabledbooltrueEnable the entire Diode stack
netboxEnterprise:
  spec:
    diode:
      enabled: false  # Disable Diode entirely

When disabled, the reconciler, ingester, auth, and Hydra components are not deployed.

Component Configuration

Each component has the same configuration structure for scaling and resources:

Reconciler

KeyTypeDefaultDescription
diode.reconciler.replicasuint81Number of reconciler replicas
diode.reconciler.resources.cpuint100CPU request (millicores)
diode.reconciler.resources.memoryint256Memory request (MiB)
diode.reconciler.limits.cpuint500CPU limit (millicores)
diode.reconciler.limits.memoryint512Memory limit (MiB)

Ingester

KeyTypeDefaultDescription
diode.ingester.replicasuint81Number of ingester replicas
diode.ingester.resources.cpuint100CPU request (millicores)
diode.ingester.resources.memoryint256Memory request (MiB)
diode.ingester.limits.cpuint500CPU limit (millicores)
diode.ingester.limits.memoryint512Memory limit (MiB)

Auth

KeyTypeDefaultDescription
diode.auth.replicasuint81Number of auth replicas
diode.auth.resources.cpuint50CPU request (millicores)
diode.auth.resources.memoryint128Memory request (MiB)
diode.auth.limits.cpuint200CPU limit (millicores)
diode.auth.limits.memoryint256Memory limit (MiB)

Hydra (OAuth2/OIDC)

KeyTypeDefaultDescription
diode.hydra.replicasuint81Number of Hydra replicas
diode.hydra.autoMigratebooltrueRun database migrations on startup
diode.hydra.resources.cpuint100CPU request (millicores)
diode.hydra.resources.memoryint256Memory request (MiB)
diode.hydra.limits.cpuint500CPU limit (millicores)
diode.hydra.limits.memoryint512Memory limit (MiB)

Hydra secrets (cookie, DSN, system) are auto-generated from the PostgreSQL configuration if not explicitly set.

Application Config

Reconciler Config

KeyTypeDefaultDescription
diode.config.reconciler.autoApplyChangesetsboolschema true; chart seeds falseAutomatically apply change sets to NetBox. The CRD schema default is true. The chart's values.yaml seeds false, and the operator forces false when NetBox Assurance is licensed so changesets go through review. Set it explicitly to override.
diode.config.reconciler.deviationRulesstringnoneDeviation rules file, as a string. The rules decide per deviation whether it is applied or held for review. Requires autoApplyChangesets: false and the NetBox Assurance entitlement. Preview. See Deviation Rules.
diode.config.reconciler.logLevelenumINFOLog level: INFO, DEBUG, WARN, ERROR
diode.config.reconciler.databaseNamestringdiodePostgreSQL database name
diode.config.reconciler.databaseUserstringdiodePostgreSQL database user
diode.config.reconciler.migrationEnabledbooltrueRun database migrations
diode.config.reconciler.redisDbuint80Redis database number
diode.config.reconciler.redisStreamDbuint81Redis database for streams
diode.config.reconciler.autoApplyProcessorConcurrencyuint81Concurrent auto-apply processors (1-255)
diode.config.reconciler.ingestionLogProcessorConcurrencyuint84Concurrent ingestion-log processors (1-255)
diode.config.reconciler.rateLimitRpsuint820Rate limit (requests/sec)
diode.config.reconciler.rateLimitBurstuint81Rate limit burst size
diode.config.reconciler.rateLimitNetboxRpsuint820NetBox API rate limit
diode.config.reconciler.rateLimitNetboxBurstuint81NetBox API burst size

Auth Config

KeyTypeDefaultDescription
diode.config.auth.logLevelenumINFOLog level

Ingester Config

KeyTypeDefaultDescription
diode.config.ingester.logLevelenumINFOLog level
diode.config.ingester.redisStreamDbuint81Redis database for stream storage
diode.config.ingester.redisMemoryHighWatermarkPctuint890Redis used_memory/maxmemory percentage at which the ingester rejects ingest with ResourceExhausted (0-100; 0 disables). Only active when Redis has a maxmemory cap -- set redis.maxMemoryPercent.

Environment Variable Overrides

Each Diode component accepts extraEnvs for per-component environment variables. User-set values override the operator's defaults. Set them on the component (not under config):

KeyTypeDescription
diode.ingester.extraEnvslistExtra environment variables for the ingester
diode.reconciler.extraEnvslistExtra environment variables for the reconciler
diode.auth.extraEnvslistExtra environment variables for the auth service
diode.hydra.extraEnvslistExtra environment variables for Hydra

Telemetry Config

Each component supports telemetry configuration:

KeyTypeDefaultDescription
telemetryConfig.environmentstring-Environment name (Diode uses its own default if not set)
telemetryConfig.metricsEnabledboolfalseEnable the Prometheus metrics endpoint for your own monitoring. With the prometheus exporter, the ingester and reconciler can open a metrics port for the operator even when this is false; see Diode metrics port and NetworkPolicy.
telemetryConfig.metricsExporterenumprometheusExporter: prometheus, otlp, console, none
telemetryConfig.metricsPortuint16-Metrics endpoint port
telemetryConfig.traceExporterenumnoneTrace exporter: otlp, console, none

Example enabling metrics for all Diode components:

netboxEnterprise:
  spec:
    diode:
      enabled: true
      config:
        ingester:
          telemetryConfig:
            metricsEnabled: true
        reconciler:
          telemetryConfig:
            metricsEnabled: true
          # autoApplyChangesets: true  # false recommended if using Assurance
        auth:
          telemetryConfig:
            metricsEnabled: true

Diode metrics port and NetworkPolicy

On connected installs, when a component uses the prometheus metrics exporter (the default), the operator reads the ingester's and reconciler's metrics port inside the cluster, so both open it even when metricsEnabled is false. With otlp, console, or none, no metrics port opens and the operator does not read that component's counters. The metrics port is a port on the pods only. No Service or ServiceMonitor is added, and the operator's own /metrics endpoint includes Diode metrics only when metricsEnabled is true. Air-gapped installs do not open it by default.

NetBox Enterprise adds a Kubernetes NetworkPolicy for each ingester and reconciler whose metrics port it opened for the operator. It is not added for a metrics port you opened yourself with metricsEnabled: true. The policy lets only the NetBox Enterprise operator reach the metrics port, and keeps open the other ports declared on the Diode pod template.

  • The policy only works where your network plugin enforces NetworkPolicy. On a cluster whose network plugin does not, any pod in the cluster can reach the metrics port.
  • Standard Kubernetes NetworkPolicies are handled automatically. If you already isolate the Diode pods with one, NetBox Enterprise adds only the rule that lets the operator reach the metrics port, and opens nothing else. It never changes or deletes your own policies.
  • Policies other than standard Kubernetes NetworkPolicies (networking.k8s.io/v1) are not detected, such as Cilium, Calico, or BaselineAdminNetworkPolicy policies. If you isolate the Diode pods with one of them, turn on the switch below so that the NetBox Enterprise policy does not re-open Diode's other ports.
  • Ports a service mesh or sidecar adds are blocked. The policy admits only the ports declared on the Diode pod template, so traffic to a port a mesh or sidecar adds without declaring it (Istio ambient mode's 15008, Linkerd's 4191, Envoy's 15090) is dropped. If the Diode pods are enrolled in Istio ambient mode, Diode traffic from mesh-enrolled clients is dropped after the upgrade to 2.5.0. To keep it, allow those ports, together with Diode's own ports, in your own NetworkPolicy.
Install typeSetting
Embedded ClusterAdmin Console Config, Show Advanced Settings, then Diode metrics NetworkPolicy admits only the operator
HelmnetworkPolicy.diodeMetricsOperatorOnly: true
networkPolicy:
  diodeMetricsOperatorOnly: true

Only turn this switch on if you manage your own network policies that allow traffic to Diode. Turned on by itself, it blocks Diode intake: the NetBox Enterprise policy then admits only the operator to the metrics port and no longer opens Diode's other ports, so any traffic to Diode that your own policies do not allow is dropped. It is off by default.

Metrics port set to a serving port: if a component's telemetryConfig.metricsPort is a port number it already uses for its normal traffic, NetBox Enterprise opens no metrics port for that component and adds no NetworkPolicy for it. The operator raises a DiodeMetricsPortCollision warning event on the NetBoxEnterprise resource. Set metricsPort to an unused port to fix it.

Data Flow

  1. External agents send data to the Ingester via gRPC
  2. The Ingester writes to Redis Streams for durable queuing
  3. The Reconciler reads from streams, processes change sets, and pushes to NetBox via its API
  4. Auth handles API key validation with Hydra providing OAuth2 token management

Next Steps

On this page