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
| Key | Type | Default | Description |
|---|---|---|---|
diode.enabled | bool | true | Enable the entire Diode stack |
netboxEnterprise:
spec:
diode:
enabled: false # Disable Diode entirelyWhen 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
| Key | Type | Default | Description |
|---|---|---|---|
diode.reconciler.replicas | uint8 | 1 | Number of reconciler replicas |
diode.reconciler.resources.cpu | int | 100 | CPU request (millicores) |
diode.reconciler.resources.memory | int | 256 | Memory request (MiB) |
diode.reconciler.limits.cpu | int | 500 | CPU limit (millicores) |
diode.reconciler.limits.memory | int | 512 | Memory limit (MiB) |
Ingester
| Key | Type | Default | Description |
|---|---|---|---|
diode.ingester.replicas | uint8 | 1 | Number of ingester replicas |
diode.ingester.resources.cpu | int | 100 | CPU request (millicores) |
diode.ingester.resources.memory | int | 256 | Memory request (MiB) |
diode.ingester.limits.cpu | int | 500 | CPU limit (millicores) |
diode.ingester.limits.memory | int | 512 | Memory limit (MiB) |
Auth
| Key | Type | Default | Description |
|---|---|---|---|
diode.auth.replicas | uint8 | 1 | Number of auth replicas |
diode.auth.resources.cpu | int | 50 | CPU request (millicores) |
diode.auth.resources.memory | int | 128 | Memory request (MiB) |
diode.auth.limits.cpu | int | 200 | CPU limit (millicores) |
diode.auth.limits.memory | int | 256 | Memory limit (MiB) |
Hydra (OAuth2/OIDC)
| Key | Type | Default | Description |
|---|---|---|---|
diode.hydra.replicas | uint8 | 1 | Number of Hydra replicas |
diode.hydra.autoMigrate | bool | true | Run database migrations on startup |
diode.hydra.resources.cpu | int | 100 | CPU request (millicores) |
diode.hydra.resources.memory | int | 256 | Memory request (MiB) |
diode.hydra.limits.cpu | int | 500 | CPU limit (millicores) |
diode.hydra.limits.memory | int | 512 | Memory limit (MiB) |
Hydra secrets (cookie, DSN, system) are auto-generated from the PostgreSQL configuration if not explicitly set.
Application Config
Reconciler Config
| Key | Type | Default | Description |
|---|---|---|---|
diode.config.reconciler.autoApplyChangesets | bool | schema true; chart seeds false | Automatically 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.deviationRules | string | none | Deviation 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.logLevel | enum | INFO | Log level: INFO, DEBUG, WARN, ERROR |
diode.config.reconciler.databaseName | string | diode | PostgreSQL database name |
diode.config.reconciler.databaseUser | string | diode | PostgreSQL database user |
diode.config.reconciler.migrationEnabled | bool | true | Run database migrations |
diode.config.reconciler.redisDb | uint8 | 0 | Redis database number |
diode.config.reconciler.redisStreamDb | uint8 | 1 | Redis database for streams |
diode.config.reconciler.autoApplyProcessorConcurrency | uint8 | 1 | Concurrent auto-apply processors (1-255) |
diode.config.reconciler.ingestionLogProcessorConcurrency | uint8 | 4 | Concurrent ingestion-log processors (1-255) |
diode.config.reconciler.rateLimitRps | uint8 | 20 | Rate limit (requests/sec) |
diode.config.reconciler.rateLimitBurst | uint8 | 1 | Rate limit burst size |
diode.config.reconciler.rateLimitNetboxRps | uint8 | 20 | NetBox API rate limit |
diode.config.reconciler.rateLimitNetboxBurst | uint8 | 1 | NetBox API burst size |
Auth Config
| Key | Type | Default | Description |
|---|---|---|---|
diode.config.auth.logLevel | enum | INFO | Log level |
Ingester Config
| Key | Type | Default | Description |
|---|---|---|---|
diode.config.ingester.logLevel | enum | INFO | Log level |
diode.config.ingester.redisStreamDb | uint8 | 1 | Redis database for stream storage |
diode.config.ingester.redisMemoryHighWatermarkPct | uint8 | 90 | Redis 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):
| Key | Type | Description |
|---|---|---|
diode.ingester.extraEnvs | list | Extra environment variables for the ingester |
diode.reconciler.extraEnvs | list | Extra environment variables for the reconciler |
diode.auth.extraEnvs | list | Extra environment variables for the auth service |
diode.hydra.extraEnvs | list | Extra environment variables for Hydra |
Telemetry Config
Each component supports telemetry configuration:
| Key | Type | Default | Description |
|---|---|---|---|
telemetryConfig.environment | string | - | Environment name (Diode uses its own default if not set) |
telemetryConfig.metricsEnabled | bool | false | Enable 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.metricsExporter | enum | prometheus | Exporter: prometheus, otlp, console, none |
telemetryConfig.metricsPort | uint16 | - | Metrics endpoint port |
telemetryConfig.traceExporter | enum | none | Trace 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: trueDiode 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, orBaselineAdminNetworkPolicypolicies. 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 type | Setting |
|---|---|
| Embedded Cluster | Admin Console Config, Show Advanced Settings, then Diode metrics NetworkPolicy admits only the operator |
| Helm | networkPolicy.diodeMetricsOperatorOnly: true |
networkPolicy:
diodeMetricsOperatorOnly: trueOnly 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
- External agents send data to the Ingester via gRPC
- The Ingester writes to Redis Streams for durable queuing
- The Reconciler reads from streams, processes change sets, and pushes to NetBox via its API
- Auth handles API key validation with Hydra providing OAuth2 token management
Next Steps
- Monitoring - Enable Diode component metrics
- Architecture - Full component topology diagram