Docs
HelmApi

Status & Conditions

NetBoxEnterprise status fields, condition types, and component health reference

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

FieldTypeDescription
componentsobjectHealth of each component. See status.components.
conditions[]ConditionCluster conditions. See Conditions.
convergedGenerationint64Highest 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.
customPythonConfigRefDigeststringShort SHA-256 digest of the ConfigMap key named by spec.netbox.config.customPythonConfigRef, as the operator last read it. A change to it makes the operator run database migrations again and restart the NetBox pods. When the ConfigMap or the key is missing, the operator keeps the last value, so a delete-and-reapply (a GitOps prune, for example) does not stop a migration that is running.
dependencyWaitStartedAtstringRFC 3339 timestamp of when the operator first saw a dependency-wait timeout for the current generation. It measures how long the wait has lasted, so a brief wait is distinguishable from a hanging one. Cleared on the first successful reconcile.
lastReconcileTimestringTimestamp of the last successful reconciliation (RFC 3339).
licenseobjectLicense details. See status.license.
licenseStatusstringComputed display string for the LICENSE column of kubectl get. Holds the license type (Dev, Trial, Paid) when the license is healthy, or the LicenseHealth condition reason when it is not. See License Information. Unset until the first reconcile completes.
messagestringHuman-readable summary of the current state.
migrationHashstringSHA-256 of migration-relevant inputs (image tag, wheelhouse, and similar). Detects when a migration must re-run.
migrationPhase1HashstringSHA-256 of Phase 1 migration inputs.
observedGenerationint64The spec generation last processed by the operator.
pasMigrationHashstringSHA-256 of the inputs of the last PAS migration that succeeded (operator version, image, resources, database source, and rendered config). The operator runs the PAS migration Job when the current inputs hash differently, or when the PAS databases read as unmigrated. A failed migration leaves it unchanged; disabling PAS clears it once no migration Job is left.
pasMigrationInFlightbooltrue once PAS has been enabled on the cluster, so that a later disable knows to clean up any PAS migration Job. Returns to false only after PAS is disabled and every migration Job and pod is removed.
phaseenumCoarse startup phase. See Startup Phase. Values: WaitingForDependencies, Migrating, InstallingPlugins, CollectingStatic, Booting, Serving, Degraded.
readyboolOverall cluster readiness - true only when all components are ready.
secretChecksumstringAggregate hash of external secret resourceVersion values. Drives the debounced restart logic.
secretChecksumObservedAtstringRFC 3339 timestamp recording when secretChecksum was last observed.
versionstringOperator version managing this cluster.
wheelhouseFingerprintstringLast-seen custom-plugin wheelhouse fingerprint from the watcher sidecar, as <mtime>_<size> or absent. Stored so the migration hash is a function of stored state only.

Example:

status:
  ready: true
  phase: Serving
  message: "All components ready"
  version: "2.5.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.

PhaseMeaning
WaitingForDependenciesPostgreSQL, Redis, or object storage is not serving yet.
MigratingThe database migration Job is running.
InstallingPluginsCustom plugins are being installed from the wheelhouse.
CollectingStaticNetBox is collecting its static files.
BootingThe NetBox pods are starting but not yet serving.
ServingNetBox is serving traffic.
DegradedA component failed. Read the conditions for the cause.

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:

ConditionStatusReasonDescription
ReadyTrueAllComponentsReadyAll components are healthy and serving traffic
ReadyFalseReconcilingA reconcile is in progress; readiness not yet confirmed
ReadyFalseComponentsNotReadyOne or more components still initializing
ReadyFalseReconcileFailedReconciliation encountered an error
ProgressingTrueApplyingResourcesOperator is actively applying resources
ProgressingTrueWaitingForComponentsResources applied, waiting for pods to become ready
ProgressingFalseReconcileCompleteReconciliation finished successfully
DegradedTrueReconcileErrorReconciliation failed - check operator logs
RoutingHealthTrueGatewayActiveNorth/south traffic is served by the Gateway API
RoutingHealthUnknownGatewayProgrammingThe Gateway was created; waiting for its controller to report Programmed=True (not yet serving)
RoutingHealthFalseGatewayNotProgrammedThe Gateway controller reports Programmed=False; its listeners are not up
RoutingHealthTrueIngressActiveNorth/south traffic is served by operator-emitted Ingress, and an ingress controller has published an address on it. Before 2.5.0, the operator reported this from the spec alone
RoutingHealthUnknownIngressPendingNew in 2.5.0: routing resolved to Ingress, and no ingress controller has published an address on the NetBox Ingress yet. Normal during startup
RoutingHealthUnknownIngressNotAdmittedNew in 2.5.0: the NetBox Ingress still has no address 5 minutes after it was created. Either no controller serves the class, or the controller serves traffic without writing Ingress status. Traffic is not affected if the controller serves it. The operator records one IngressNotAdmitted Warning event
RoutingHealthTrueIngressFallbackspec.gateway is enabled but the Gateway API is unavailable (CRDs absent or RBAC missing); serving via Ingress
RoutingHealthUnknownIngressFallbackNew in 2.5.0: the same fallback to Ingress, but no ingress controller has published an address on the NetBox Ingress yet
RoutingHealthFalseRoutingModeMismatchThe resolved routing path is disabled (e.g. mode: gateway with spec.gateway.enabled: false); nothing is emitted
PluginsReadyTruePluginsImportableAll enabled plugins import successfully
PluginsReadyFalsePluginUnimportableAn enabled plugin failed to import; the message names it
PluginsReadyFalseSettingsLoadFailedNetBox settings failed to load before any single plugin could be blamed (an enabled plugin broke settings import, or an invalid Python config override)
LeaderElectedTrueLeaderElectionAcquiredThe operator pod named in message holds the leader lease. Present only on HA (multi-replica) operator deployments; only the leader writes status.
HANotEnabledTrueHANotEnabledGates Ready. 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. Embedded Cluster only — a Helm install has no such signal, so this condition does not appear.
HAWithoutExternalDataTrueHAWithoutExternalDataGates Ready. Operator HA is enabled but a data tier cannot survive node loss. The message names which of PostgreSQL, Redis, or object storage is at fault. Requires a confirmed Embedded Cluster HA signal, so this condition never appears on a Helm install — see the note below.
SharedStorageNotMultiNodeTrueSharedStorageNotMultiNodeAdvisory: netbox.replicas is above 1 with ReadWriteOnce/ReadWriteOncePod media and scripts volumes and object storage off, so the extra replicas will hang on volume multi-attach. Suppressed when object storage is in use. Never gates Ready, because the combination is legitimate on a single node or with pinned scheduling.
InClusterStorageBelowNodeGateTrueInClusterStorageBelowNodeGateAdvisory: storageBackend is in-cluster but the cluster has fewer than 3 nodes, so all three Garage replicas can share a node and the store holds no real redundancy. Derived from the live node count, so it does apply to Helm installs. Does not gate Ready.
MultiNodeNotEntitledTrueMultiNodeNotEntitledAdvisory: the cluster has 3 or more nodes but the license lacks the multi-node entitlement, so in-cluster PostgreSQL and Redis scaling is capped at a single instance. Does not gate Ready — a capped tier still runs correctly.
AssetLifecycleFalseRequiresPremiumLicenseAsset Lifecycle was requested but the license is below Premium, so it was not enabled
AssetLifecycleFalseConflictsWithNetboxInventoryAsset Lifecycle was requested but netbox_inventory is present, so it was not enabled
AssetLifecycleFalseConflictsWithNetboxLifecycleAsset Lifecycle was requested but netbox_lifecycle is present, so it was not enabled
NdxReadyFalseMissingTokenNDX was requested (spec.plugins.ndx.enabled, which defaults to true) but the license carries no paid NDX token, so NDX was not enabled. NetBox keeps running. Present only in that state. See NetBox Data Exchange.
RedisSpreadHeldTrueRedisSpreadHeldAdvisory: two or more in-cluster Redis pods share a node and their ReadWriteOnce volumes pin them there, so the hard one-pod-per-node spread is held as a soft preference. Redis serves normally but is not protected against losing that node, and the state is permanent until an operator acts. Does not gate Ready. See Recovery steps.
TlsCaTrustFalseCaSecretMissingA referenced CA secret is absent, empty, or holds no PEM certificate. Covers both the keychainCaCertificates references of a TLS-verifying service (Redis, PostgreSQL, S3) and the global spec.extraCaCertificates entries. Surfaced here so the failure is visible before the bundle init container fails fast at runtime.
TlsCaTrustTrueCaTrustResolvedThe cluster references at least one CA secret and every one of them resolves.
WheelhouseSourceProbeFalseSourceUnreachableThe configured custom-plugin wheelhouse source could not be reached. See Custom Plugins.
MigrationSucceededTrue / False—Reports the outcome of the most recent database migration.
SuperuserSecretFalseSuperuserSecretKeyMissingGates the NetBox pod, not Ready. A bring-your-own superuser Secret exists but does not carry a key named against it. The NetBox pod then never starts, and nothing else operator-side says why. See spec.netbox.config.superuser.
SuperuserSecretFalseSuperuserSecretMissingA named superuser Secret is absent. Self-correcting: a resource may be applied ahead of its Secret, and the condition flips True once the Secret exists.
SuperuserSecretTrueSuperuserSecretResolvedEvery superuser Secret key resolves.
SpecManuallyEditedTrueManualEditDetectedAdvisory: kubectl edit or kubectl patch changed fields in the resource's spec. On Embedded Cluster 2.15.0 and later, an admin console deploy that sets a different value for one of those fields fails with a field-manager conflict. The message names the fields and the field manager. To recover, delete that field manager's entry from metadata.managedFields, then deploy again. Does not gate Ready.
SpecManuallyEditedFalseNoManualEditsNo kubectl edit or kubectl patch field manager owns a field in spec.
ClusterScopedFeaturesTrueClusterScopedAdvisory, new in 2.5.0: the operator is cluster-scoped, so its RBAC scope disables no features. It does not check that the ClusterRole grants them. Does not gate Ready.
ClusterScopedFeaturesFalseNamespaceScopedAdvisory, new in 2.5.0: the operator runs with rbac.scope: namespace. The message names each feature that scope disables. Does not gate Ready. See Namespace-Scoped Installation.
DatabaseConnectionBudgetExceededTrueDatabaseConnectionBudgetExceededAdvisory, new in 2.5.0: the NetBox web pods can open more PostgreSQL connections than the database allows them (replicas × GRANIAN_WORKERS × GRANIAN_BACKPRESSURE, against max_connections less the reserved connections). The message gives the numbers. Under load, NetBox returns errors once PostgreSQL runs out of connections. On Helm, raise spec.postgresql.maxConnections. On Embedded Cluster, choose a larger PostgreSQL resources preset in the Admin Console. You can also lower GRANIAN_BACKPRESSURE or the replica count. Present only with operator-managed PostgreSQL. Does not gate Ready.
IdentityProviderTrueProvisionedAdvisory, new in 2.5.0: the bundled Keycloak realm import is complete. Does not gate Ready.
IdentityProviderUnknownProvisioningThe realm import is in progress.
IdentityProviderUnknownKeycloakNotReadyThe bundled Keycloak exists but is not ready. The message names the cause.
IdentityProviderUnknownHealthUnconfirmedKeycloak reports ready again, but the operator could not confirm the realm and sign-in client on this pass. It checks again on the next reconcile.
IdentityProviderUnknownGatewayPolicyRejectedThe realm is provisioned, but the gateway does not honor the BackendTLSPolicy that protects /sso. The message gives the gateway's answer.
IdentityProviderUnknownGatewayPolicyUnconfirmedThe realm is provisioned, but the gateway has not reported that it accepted that BackendTLSPolicy. Until it does, nothing confirms that requests to /sso reach Keycloak.
IdentityProviderFalsePendingHostThe bundled identity provider has no host to serve sign-in on. It needs Gateway routing: an install that routes through Ingress always reports this. Under Gateway routing it takes the first concrete listener hostname or, when the listeners declare no hostname, the first spec.ingress.tls host. On Embedded Cluster, that is the NetBox Hostname. See Platform Single Sign-On.
IdentityProviderFalseNamespaceScopedUnsupportedThe operator runs with rbac.scope: namespace. The bundled Keycloak creates cluster-scoped roles, so it cannot be installed.
IdentityProviderFalseother reasons, listed below the tableThe bundled Keycloak failed to provision or has drifted. The message names the cause and the fix. NetBox itself is unaffected.
IdentityFederationTrueFederationConsistentAdvisory, new in 2.5.0: the realm's identity providers match spec.idp. For SAML, the message also gives when the signing certificate expires. Does not gate Ready.
IdentityFederationFalseBundledKeycloakDisabledA federation source is enabled, but spec.idp.enabled is false. Federation runs through the bundled Keycloak, so no federated sign-in can succeed. On Helm, set both the chart value idp.enabled and netboxEnterprise.spec.idp.enabled to true. In the Admin Console, select Enable Bundled Keycloak.
IdentityFederationFalseCredentialsRejectedThe OIDC provider refused the client ID or client secret, so every federated sign-in fails. The message names which credential and where to fix it. The operator checks again hourly, and right after the client ID, token URL, client secret, or spec.extraCaCertificates changes.
IdentityFederationFalseFederationCredentialRefusedThe Secret holding the OIDC client secret or the LDAP bind password does not have the label netboxlabs.com/federation-credential=true, so the operator did not read it. If Keycloak already holds the provider or directory, it keeps the stored credential, but a rotated credential does not reach it. On a first install, the provider or directory is not created. The message gives the command that adds the label.
IdentityFederationUnknownProviderUnreachableThe operator could not check the OIDC client credentials (no route, a TLS or proxy failure, or an answer it cannot classify). Says nothing about whether sign-in works.
IdentityFederationFalseUndeclaredFederationSourceThe realm holds an enabled identity provider or LDAP directory that spec.idp does not declare. Only one federation source may be live. The operator never deletes one, so disable or delete it in the Keycloak admin console, or declare it in spec.idp.
IdentityFederationFalseFederationNotReconciledThe operator could not bring a provider to the state spec.idp describes. The KeycloakFederationUnavailable events name the cause.
IdentityFederationFalseLdapConnectionFailedKeycloak cannot bind to the LDAP directory, so every LDAP login fails. Check connectionUrls, bindDn, and the bind credential Secret.
IdentityFederationFalseSigningCertificateInvalidNo configured SAML signing certificate is valid now, so Keycloak refuses every SAML login.
IdentityFederationFalseSigningCertificateUnreadableThe SAML signing certificate Secret cannot be read. The operator keeps the provider disabled until the Secret holds a usable certificate. Local accounts still sign in.
IdentityFederationFalseSigningCertificateExpiringThe last valid SAML signing certificate expires within 30 days. Add the new certificate to the Secret beside the current one before then.
IdentityFederationUnknownFederationUnconfirmedThe operator could not read the realm's identity providers, or could not test the LDAP bind, on this pass. The message names which.
LegacyDirectOidcTrueDirectOidcConfiguredAdvisory, new in 2.5.0: NetBox authenticates directly against your own OIDC provider, configured in spec.netbox.config.customPythonConfig. The operator names federation through the bundled Keycloak (spec.idp.oidcFederation) as the supported path, but in this release the two are independent: federation signs people in to the platform interface, not to NetBox, and nothing migrates one to the other. Keep your direct NetBox SSO. See Moving from direct NetBox SSO. Not detected when the backend is set only in customPythonConfigRef. Does not gate Ready.
PasDatabaseTrueDatabasesReadyAdvisory, new in 2.5.0: both authorization server databases exist, the migrate role owns them, and the schema grants are confirmed. Does not gate Ready.
PasDatabaseFalseNotConfiguredspec.postgresql.external is set but spec.pas.postgres is not, so the authorization server was not deployed. Create the migrate and runtime roles and the platform_auth and platform_auth_fga databases, then set spec.pas.postgres.
PasDatabaseFalsePostgresMismatchspec.pas.postgres is set but spec.postgresql.external is not, so the authorization server was not deployed. NetBox and the authorization server always share one PostgreSQL server. Remove spec.pas.postgres to use the operator-managed database.
PasDatabaseFalseConnectionInvalidspec.pas.postgres cannot become a connection: a malformed URL, an unreadable Secret key, or unusable role names. The message says which.
PasDatabaseFalseUnreachableThe operator ran out of retries without a usable connection, either because the server never accepted one or because statements kept failing. The message says which.
PasDatabaseFalseAuthenticationFailedThe server rejected the migrate role's credential.
PasDatabaseFalseDatabaseMissingplatform_auth or platform_auth_fga does not exist. The names are fixed.
PasDatabaseFalseDatabaseNotOwnedByMigrateRoleA database exists but another role owns it. Grants on it would succeed and confer nothing, so make the migrate role the owner.
PasDatabaseFalseInsufficientPrivilegePostgreSQL refused a statement for lack of privilege.
PasDatabaseFalseGrantsIneffectiveEvery grant returned success, but the runtime role does not hold the privileges it was granted.
PasMigrationFalseMigrateJobFailedAdvisory, new in 2.5.0: the authorization server's migrate Job failed and is not retried. NetBox is unaffected, but authorization stays down until the migration succeeds. Fix the cause, or delete the Job to retry the same configuration. The message names the Job. Does not gate Ready.
PasMigrationFalseDatabasesNotMigratedThe authorization server databases have no applied migration although one was recorded, usually because they were dropped and recreated or skipped by a restore. The operator runs the migration again. If the Job completes and the condition stays, delete the Job.
PasSecretFalseSecretRefusedAdvisory, new in 2.5.0: the authorization server's crypto Secret (<name>-pas-secrets) is missing keys the operator will not regenerate. The authorization server is held at its current state until the Secret is repaired. NetBox keeps reconciling. The message names the missing keys and both ways to recover. Does not gate Ready.
PlatformUiIngressRefusedTrueShellIngressCompetesWithNetBoxAdvisory, new in 2.5.0: spec.ui.enabled is set but routing resolves to Ingress. The operator does not create the platform UI Ingress, because it would claim / on every hostname, including NetBox's. The platform UI still runs; only its entry point is withheld. To serve it, use Gateway routing with a wildcard listener that admits spec.ui.hostname. Does not gate Ready.
SccIdentityAdvisoryTrueSccInjectsNoIdentityAdvisory, new in 2.5.0: the SCC that admits the pods assigns no UID or fsGroup, so the operator sets both itself. To have OpenShift assign them, remove that SCC's binding or lower its priority below restricted-v2. Does not gate Ready.
SccIdentityAdvisoryTrueSccVerdictHeldThe SCC that admits the pods changed, but the operator keeps the identity the data was created with. Running pods keep working. A restarted pod can fail admission or lack the UID its data needs. Restore the previous SCC binding.
SccIdentityAdvisoryTrueSccReviewUnavailableThe operator could not check which SCC admits the pods, so it keeps the current identity without checking.
VisualExplorerReadyFalseNotEntitledThe platform UI is enabled and requests Visual Explorer (spec.ui.remotes.visualExplorer defaults to true), but the license lacks the entitlement, so the Visual Explorer tab is not deployed. Set spec.ui.remotes.visualExplorer: false to stop requesting it. Present only in that state. Does not gate Ready.
VeleroRestoreConfigInvalidTruefive reasons, belowAdvisory: the velero namespace does not hold exactly one usable pod-volume-restore plugin config, so a future restore cannot return your volume data. See Velero restore plugin config. Does not gate Ready -- nothing is wrong with the running cluster.

The other False reasons of IdentityProvider, each with a message that names the cause and the fix: ImportFailed, ClientMissing, ClientConfigDrift, ClientRedirectRealignFailed, ServiceAccountAuthUnavailable, KeycloakAdminUnavailable, DatabaseConnectionFailed, KeycloakSchemaMissing, KeycloakDbProvisionFailed, KeycloakDbCredentialDamaged, KeycloakServingCertFailed, KeycloakServingCaConfigMapFailed, TruststoreCaUnresolved, KeycloakCrdMissing, KeycloakRbacDenied, KeycloakApplyConflict, KeycloakApplyFailed.

New in 2.3.0, the four PostgreSQL restore conditions:

ConditionStatusGates Ready?Description
PostgresRestorePendingTrueNoA restored cluster whose PostgreSQL is wedged. Patroni failed to bootstrap over the empty data volume that a Velero restore leaves behind, and the instance pod parks with its database container not ready. The dependency wait already holds Ready=Unknown, so this condition only names the cause. See PostgreSQL Backups and Disaster Recovery.
PostgresRecoveryRequiredTrueYesA restored cluster whose PostgreSQL bootstrapped cleanly over an empty data volume. Every other surface reports success, and the cluster serves a database with none of your data in it. Derived live from Velero's velero.io/restore-name label and PGO's own PostgresDataInitialized condition, so it clears itself once the database is back.
PostgresRestoreFailedTrueYesThe pgBackRest restore Job is failing. It shows after several failed attempts: on the tested installs, after two to five attempts, up to five minutes. PostgreSQL is shut down for the whole retry cycle, so Ready is Unknown with WaitingForDependencies while it shows. It clears once PGO reports a database. See Restore fails in a loop.
PostgresReconciliationPausedTrueNoPGO paused reconciliation of the PostgresCluster because PostgreSQL backups were disabled on a live cluster. The pause is total: no spec change, no upgrade, and no resource change reaches the database, while the database keeps serving. Set spec.postgresql.backups.enabled back to true to resume.

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.

StatusReasonDescription
TrueFilesystemNearlyFullThe filesystem that holds the repository is 70% full or more. On Embedded Cluster the repository shares the node's disk, so the message also says when most of the used space is outside the repository.
TrueRepoOverRequestThe repository is larger than spec.postgresql.backups.repoStorageSize. On Embedded Cluster that size is not a limit, so the repository keeps growing.
FalseWithinLimitsThe latest reading is below both limits.
UnknownReadingStaleThe latest reading was below both limits, but it is more than 3 hours old.
UnknownProbeFailingThe probe has never produced a reading. The message gives the error from its latest run.
UnknownProbeNotInstalledThe probe CronJob does not exist. The RepoUsageProbeFailed events on the NetBoxEnterprise give the reason.
UnknownProbeUnreadableThe operator could not read the probe's Jobs and pods.
UnknownNoProbeHistoryNo probe run is left to read. This is the state of a new cluster before the first hourly run, and of a cluster whose probe runs are gone after an earlier reading. The next hourly run replaces it.

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:

ReasonWhat is wrong
VeleroRestoreConfigMissingNo ConfigMap matches the selector.
VeleroRestoreConfigDuplicatedMore than one matches, and Velero needs one.
VeleroRestoreConfigUnparseableThe secCtx key is not valid YAML.
VeleroRestoreSecCtxIncompleteThe secCtx omits a required key.
VeleroRestoreSecCtxUnsafeA key holds a value the restore cannot survive.

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.

Ready is a weaker signal on Helm than on Embedded Cluster

HANotEnabled and HAWithoutExternalData are the two conditions that gate Ready, and both depend on an Embedded Cluster signal that a Helm install does not have. On Helm, a data tier that cannot survive node loss therefore produces no condition and no effect on Ready. Verify replica counts directly — see High Availability.

Each condition includes:

FieldTypeDescription
typestringCondition type
statusstringTrue, False, or Unknown
reasonstringMachine-readable reason code
messagestringHuman-readable detail
lastTransitionTimestringWhen the condition last changed
observedGenerationint64Spec 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}'

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
TypeStatusReasonDescription
LayoutAppliedTrueLayoutAppliedGarage has applied its storage layout
LayoutAppliedFalseLayoutPendingThe storage layout has not been applied yet
ServingTrueClusterServingGarage reports a write quorum for every partition and answers an S3 round-trip
ServingFalseClusterNotServingGarage does not yet report a write quorum for every partition
ReadyTrueGarageServingGarage is laid out and serving S3 requests
ReadyFalseLayoutPendingGarage is not yet both laid out and serving
ReadyFalseWaitingForPodsToo few StatefulSet pods are Ready to reach the admin API — ordinary first-provision startup
ReadyFalseQuorumLostToo few pods are Ready and a layout already exists, so the cluster has lost quorum and genuinely cannot serve
ReadyFalseReconcileFailedReconciliation encountered an error
GarageSpreadHeldTrueGarageSpreadHeldAdvisory: two or more Garage pods share a node and their ReadWriteOnce volumes pin them there, so the hard one-pod-per-node spread is held as a soft preference. Object storage serves normally but is not protected against losing that node. See A held Garage spread.

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:

FieldTypeDescription
copilotobjectCopilot backend (present when Copilot is enabled).
diodeobjectData ingestion pipeline (if enabled).
netboxobjectWeb application deployment.
pas.conditions[]ConditionOne Ready condition for PAS. Its reason is IdentityProviderRequired when PAS is enabled but cannot be deployed.
pas.messagestringHuman-readable PAS state: the replica readiness of the PAS Deployment, PAS not enabled, or a note that PAS is enabled but not deployed because it needs the identity provider and a listener hostname.
pas.readyboolWhether the PAS Deployment is ready; true when PAS is not enabled. A deployed PAS that is not ready holds the whole cluster at not ready. An enabled PAS that cannot be deployed reports false without affecting cluster readiness.
postgresqlobjectDatabase (internal or external).
redisobjectCache/queue.
ui.conditions[]ConditionThe platform UI's Ready condition: True with reason ComponentReady, or False with reason NotReady when a UI Deployment is missing or not rolled out.
ui.messagestringPlatform UI status in words: Platform UI not enabled, a count of ready components, or the reason each failing UI Deployment is not ready.
ui.readyboolWhether the shell and every enabled remote Deployment have rolled out. Also true when the platform UI is off. While the UI is on, false here keeps the cluster from reporting ready.
workerobjectBackground task worker.

Each component has:

FieldTypeDescription
conditions[]ConditionComponent-specific conditions.
messagestringHuman-readable status (e.g., "2/2 replicas ready").
readyboolWhether the component is ready.

Component conditions carry their own reason codes:

ReasonCondition / StatusDescription
ComponentReadyReady / TrueThe component is healthy and serving
ProgressingProgressing / TrueThe component is starting or rolling out
NotReadyReady / FalseThe component is not yet ready
UnknownReady / FalseComponent health could not be determined (for example, PostgreSQL or Redis status was unavailable)
IdentityProviderRequiredReady / Falsestatus.components.pas only, new in 2.5.0: spec.pas.enabled is set, but the authorization server was not deployed, because it needs the bundled identity provider and a Gateway listener hostname. Does not count against Ready

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:

FieldTypeDescription
channelNamestringChannel (stable, beta, dev).
customerEmailstringCustomer email.
customerNamestringCustomer name.
editionenumDead field. The operator no longer writes it. It stays in the schema so a status written by an older operator still parses. Do not read it. Values: Community, Enterprise.
entitlements.<name>.titlestringDisplay name of the entitlement. The map is the raw entitlements map from the license, keyed by entitlement name.
entitlements.<name>.valueanyValue of the entitlement, of any JSON type.
expiresAtstringExpiration date (ISO 8601).
isAssuranceEntitledboolWhether NetBox Assurance features are available.
isCopilotEntitledboolWhether Private Copilot is entitled by the license (defaults false).
isNdxEntitledboolWhether NetBox Data Exchange is entitled, meaning the license carries a paid NDX token. New in 2.3.0. See NetBox Data Exchange.
isVisualExplorerEntitledboolWhether Visual Explorer, the first UI Platform app, is entitled. New in 2.3.0.
licenseIdstringUnique license identifier.
licenseTypestringLicense type (dev, trial, prod, paid).
platformOrgIdstringPlatform organization ID from the license.
tierenumThe tier your license carries. Community is the base tier of every license; Professional and Premium add features. Values: Community, Professional, Premium.
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.

ConditionStatusReasonDescription
LicenseHealthTrueLicenseValidThe license is present and current.
LicenseHealthFalseLicenseExpiredThe license is past its expiry date. Enterprise features may be unavailable. Renew it in the Replicated vendor portal.
LicenseHealthFalseLicenseUnavailableNo license could be fetched and no cached license exists. Check that the in-cluster Replicated SDK is reachable. Reconciliation is blocked until a license is available.
LicenseHealthFalseLicenseUnrecognizedThe SDK answered with a license type this release does not recognize. Distinct from LicenseUnavailable, which means no answer at all.
LicenseHealthFalseLicenseInvalidThe license failed a tamper check. Reconciliation is blocked while that stands.

The LICENSE column's own help text, which kubectl explain prints, names a LicenseMismatch reason. The operator does not emit that reason. Read the five rows above as the real set.

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

On this page