Status & Conditions

The operator maintains a detailed status on each NetBoxEnterprise resource. Use this to monitor cluster health, troubleshoot issues, and integrate with monitoring systems.

Viewing Status

# Summary view
kubectl -n netbox get netboxenterprises -o wide

# Detailed status
kubectl -n netbox describe netboxenterprise netbox

# JSON output for scripting
kubectl -n netbox get netboxenterprise netbox -o jsonpath='{.status}'

Top-Level Status Fields

Field	Type	Description
ready	bool	Overall cluster readiness - true only when all components are ready
message	string	Human-readable summary of the current state
version	string	Operator version managing this cluster
observedGeneration	int64	The spec generation last processed by the operator
convergedGeneration	int64	Highest spec generation that has reached all-components-ready. When it equals metadata.generation, the current config rollout has converged and the progress sentinel reports Ready.
lastReconcileTime	string	Timestamp of the last successful reconciliation (RFC 3339)
migrationHash	string	SHA-256 of migration-relevant inputs (image tag, wheelhouse, and similar). Detects when a migration must re-run.
migrationPhase1Hash	string	SHA-256 of Phase 1 migration inputs
secretChecksum	string	Aggregate hash of external secret resourceVersion values. Drives the debounced restart logic.
secretChecksumObservedAt	string	RFC 3339 timestamp recording when secretChecksum was last observed

Example:

status:
  ready: true
  message: "All components ready"
  version: "2.2.0"
  observedGeneration: 3
  convergedGeneration: 3
  lastReconcileTime: "2026-06-08T10:30:00Z"

Conditions

Standard Kubernetes conditions on the NetBoxEnterprise resource:

Condition	Status	Reason	Description
Ready	True	AllComponentsReady	All components are healthy and serving traffic
Ready	False	Reconciling	A reconcile is in progress; readiness not yet confirmed
Ready	False	ComponentsNotReady	One or more components still initializing
Ready	False	ReconcileFailed	Reconciliation encountered an error
Progressing	True	ApplyingResources	Operator is actively applying resources
Progressing	True	WaitingForComponents	Resources applied, waiting for pods to become ready
Progressing	False	ReconcileComplete	Reconciliation finished successfully
Degraded	True	ReconcileError	Reconciliation failed - check operator logs
RoutingHealth	True	GatewayActive	North/south traffic is served by the Gateway API
RoutingHealth	Unknown	GatewayProgramming	The Gateway was created; waiting for its controller to report Programmed=True (not yet serving)
RoutingHealth	False	GatewayNotProgrammed	The Gateway controller reports Programmed=False; its listeners are not up
RoutingHealth	True	IngressActive	North/south traffic is served by operator-emitted Ingress
RoutingHealth	True	IngressFallback	spec.gateway is enabled but the Gateway API is unavailable (CRDs absent or RBAC missing); serving via Ingress
RoutingHealth	False	RoutingModeMismatch	The resolved routing path is disabled (e.g. mode: gateway with spec.gateway.enabled: false); nothing is emitted
PluginsReady	True	PluginsImportable	All enabled plugins import successfully
PluginsReady	False	PluginUnimportable	An enabled plugin failed to import; the message names it
PluginsReady	False	SettingsLoadFailed	NetBox settings failed to load before any single plugin could be blamed (an enabled plugin broke settings import, or an invalid Python config override)
LeaderElected	True	LeaderElectionAcquired	The operator pod named in message holds the leader lease. Present only on HA (multi-replica) operator deployments; only the leader writes status.
HANotEnabled	True	HANotEnabled	Advisory: the cluster has 3 or more nodes but operator high availability is not enabled. Present only in that state. Run netbox-enterprise enable-ha to complete the setup.
HAWithoutExternalData	True	HAWithoutExternalData	Advisory: operator HA is enabled but the data tier is not fully externalized. The message lists which of external PostgreSQL, Redis, or object storage must be externalized for the cluster to survive node loss.

Each condition includes:

Field	Type	Description
type	string	Condition type
status	string	True, False, or Unknown
reason	string	Machine-readable reason code
message	string	Human-readable detail
lastTransitionTime	string	When the condition last changed
observedGeneration	int64	Spec generation when set

Inspecting Conditions

# Get conditions as a table
kubectl -n netbox get netboxenterprise netbox -o jsonpath='{range .status.conditions[*]}{.type}{"\t"}{.status}{"\t"}{.reason}{"\t"}{.message}{"\n"}{end}'

Component Status

Each component reports its own health under status.components:

Component	Key	Description
NetBox app	components.netbox	Web application deployment
NetBox worker	components.worker	Background task worker
PostgreSQL	components.postgresql	Database (internal or external)
Redis	components.redis	Cache/queue
Diode	components.diode	Data ingestion pipeline (if enabled)
Copilot	components.copilot	Copilot backend (present when Copilot is enabled)

Each component has:

Field	Type	Description
ready	bool	Whether the component is ready
message	string	Human-readable status (e.g., "2/2 replicas ready")
conditions	[]Condition	Component-specific conditions

Component conditions carry their own reason codes:

Reason	Condition / Status	Description
ComponentReady	Ready / True	The component is healthy and serving
Progressing	Progressing / True	The component is starting or rolling out
NotReady	Ready / False	The component is not yet ready
Unknown	Ready / False	Component health could not be determined (for example, PostgreSQL or Redis status was unavailable)

A component that fails also sets Degraded / True with a component-specific reason and the failure detail in message.

Inspecting Component Health

# All component statuses (components is an object keyed by component name)
kubectl -n netbox get netboxenterprise netbox \
  -o jsonpath='{.status.components}' | jq

# Specific component
kubectl -n netbox get netboxenterprise netbox \
  -o jsonpath='{.status.components.postgresql}'

License Information

License details are surfaced in status.license:

Field	Type	Description
tier	enum	Community, Starter, Professional, Premium
edition	enum	Community, Enterprise
licenseId	string	Unique license identifier
licenseType	string	License type (dev, trial, prod, paid)
customerName	string	Customer name
customerEmail	string	Customer email
channelName	string	Channel (stable, beta, dev)
isAssuranceEntitled	bool	Whether NetBox Assurance features are available
isCopilotEntitled	bool	Whether Private Copilot is entitled by the license (defaults false)
platformOrgId	string	Platform organization ID from the license
entitlements	map	Raw entitlements map keyed by entitlement name. Each entry has a title (string) and a value (any JSON type). Used for additional checks.
expiresAt	string	Expiration date (ISO 8601)

kubectl -n netbox get netboxenterprise netbox -o jsonpath='{.status.license}'

Generation Tracking

The operator tracks observedGeneration to detect configuration drift:

• metadata.generation: Incremented by Kubernetes when spec changes
• status.observedGeneration: Set by the operator after processing a generation

If observedGeneration < metadata.generation, the operator has not yet processed the latest spec change.

# Check for pending changes
kubectl -n netbox get netboxenterprise netbox \
  -o jsonpath='gen={.metadata.generation} observed={.status.observedGeneration}'

Reconciliation Events

The operator publishes Kubernetes events for each reconciliation:

# All operator events
kubectl -n netbox get events --field-selector source=nbe-operator

# Watch events in real time
kubectl -n netbox get events -w --field-selector source=nbe-operator

Event types include:

• Normal: Resource applied successfully, reconciliation complete
• Warning: Readiness check failed, reconciliation error

See Also

• Troubleshooting - Using status to diagnose issues
• NetBoxEnterprise CRD - Full spec reference