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

Example:

status:
  ready: true
  phase: Serving
  message: "All components ready"
  version: "2.4.0"
  licenseStatus: "Paid"
  observedGeneration: 3
  convergedGeneration: 3
  lastReconcileTime: "2026-06-08T10:30:00Z"

Startup Phase

status.phase reports where an install has reached. Without it, a multi-minute install shows only an opaque 503. The Admin Console and the kubectl printer columns both read this field.

The variants are ordered along the install timeline. The operator observes WaitingForDependencies, Migrating, Serving, and Degraded directly, from the dependency-wait timer, the migration Job status, component readiness, and the existing conditions. The three in-pod phases -- InstallingPlugins, CollectingStatic, and Booting -- happen inside the NetBox entrypoint, which reports them back through a startup table the operator reads.

kubectl -n netbox get netboxenterprise netbox -o jsonpath='{.status.phase}{"\n"}'

Conditions

Standard Kubernetes conditions on the NetBoxEnterprise resource:

New in 2.3.0, the four PostgreSQL restore conditions:

PostgresRestoreFailed is a useful signal when it is present, and its absence proves nothing. On a cluster with no primary pod at all, the condition can be absent while the restore is still failing. Read status.pgbackrest.restore on the PostgresCluster directly in that case.

New in 2.4.0, PostgresBackupRepoPressure reports how full the pgBackRest backup repository is. An hourly probe CronJob measures it. The condition is advisory and does not gate Ready. It is absent when PostgreSQL is external and when backups are off. Before the first probe run, it is Unknown with NoProbeHistory. The operator records an event each time the condition changes. It does not measure the PostgreSQL data volume, where WAL waits when archiving fails. See What fills the PostgreSQL data volume.

A probe failure does not clear a True condition. The condition stays True, and its message adds the failure, so an alert on it does not clear while the probe is down.

When the condition is True, lower spec.postgresql.backups.retentionFull, or take full backups more often, and then expire the old backups. Do not raise repoStorageSize on Embedded Cluster: its storage class cannot expand a volume, so the reconcile fails. See PostgreSQL Backups and Disaster Recovery.

The AssetLifecycle condition is only present when Asset Lifecycle was requested and gated off. It is absent when Asset Lifecycle is disabled, and absent when it is enabled and healthy. See Asset Lifecycle Management.

TlsCaTrust is absent entirely when the cluster configures no custom CA trust, so an install that never asked for one carries no condition about it.

SuperuserSecret is absent when the operator generates the superuser credentials, because it then writes the very keys it reads.

Velero restore plugin config

Velero restores a filesystem-backed volume through a restore-wait init container, and it reads that container's security context from a ConfigMap in the velero namespace. It finds the ConfigMap by label selector, and it needs exactly one match.

The operator checks that on every reconcile and reports VeleroRestoreConfigInvalid when the check fails. The reason names which of five faults applies:

Read the reason first for the kind of fault, then read the message for the detail you act on. Only the message says which ConfigMaps matched, or which keys are absent.

The condition is absent when Velero is not installed. It is also absent under rbac.scope: namespace, because the reads are cross-namespace: the operator emits nothing rather than a false alarm. A namespace-scoped install has to run the count itself:

kubectl get configmap -n velero \
  -l 'velero.io/plugin-config,velero.io/pod-volume-restore=RestoreItemAction'

See The pod-volume-restore plugin config for what to do about each fault.

Each condition includes:

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}'

GarageCluster Conditions

When in-cluster object storage is enabled, the object store is a separate GarageCluster resource with its own conditions. These do not appear on the NetBoxEnterprise resource, so kubectl describe netboxenterprise will not show them:

kubectl -n netbox describe garagecluster

Ready is the conjunction of LayoutApplied and Serving, so a held spread cannot gate it — the store is serving, it just is not protected.

Component Status

Each component reports its own health under status.components:

Each component has:

Component conditions carry their own reason codes:

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:

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

The operator also reports a LicenseHealth condition. status.licenseStatus carries the same verdict as one string, which is what the LICENSE column of kubectl get netboxenterprise prints.

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