# Architecture (/docs/enterprise/helm/guides/architecture)



The nbe-operator is a Kubernetes operator that manages the full lifecycle of a NetBox Enterprise deployment through a `NetBoxEnterprise` custom resource.

## Operator Reconciliation Flow [#operator-reconciliation-flow]

When a `NetBoxEnterprise` resource is created or modified, the operator reconciles the desired state into Kubernetes resources (see [Figure 1](#figure-1-reconciliation-flow)).

The operator uses a debounced watch strategy: rapid changes are batched with a 5-second debounce window to avoid excessive reconciliation.

When `spec.suspend` is `true`, the operator stops applying resource changes (it logs `Suspension enabled - skipping resource application` and waits for the next spec change). Existing workloads continue running. This is useful for pausing the operator during troubleshooting. See [Suspend Reconciliation](/enterprise/helm/installation/upgrading#suspend-reconciliation).

The cluster DNS suffix used for all operator-generated FQDNs defaults to `cluster.local` and can be overridden via `spec.clusterDnsSuffix` in the NetBoxEnterprise resource.

## Resource Application Order [#resource-application-order]

Resources are applied in a strict canonical order to respect dependencies:

| Order | Resource Type                | Example                                         |
| ----- | ---------------------------- | ----------------------------------------------- |
| 1     | PostgresCluster              | PGO-managed database (skipped if external)      |
| 2     | RedisCluster                 | Operator-managed Redis (skipped if external)    |
| 3     | Secret                       | Application secrets, credentials                |
| 4     | ConfigMap                    | Application configuration                       |
| 5     | ServiceAccount               | RBAC identities                                 |
| 6     | Role                         | RBAC permissions                                |
| 7     | RoleBinding                  | RBAC bindings                                   |
| 8     | PersistentVolumeClaim        | Media and script storage                        |
| 9     | Deployment                   | NetBox, workers, Diode components               |
| 10    | Job                          | Bootstrap, migrations, setup                    |
| 11    | Service                      | Internal and external services                  |
| 12    | Gateway API routes / Ingress | External access (per the resolved routing mode) |
| 13    | VeleroBackup                 | Backup configuration (enterprise)               |

Readiness middleware ensures PostgreSQL and Redis are available before deployments are created.

## Component Topology [#component-topology]

The nbe-operator sits at the center of the deployment, reconciling all application components while delegating database and cache lifecycle to dedicated operators (see [Figure 2](#figure-2-component-topology)).

PostgreSQL and Redis are managed by their own dedicated operators: [Crunchy PGO](https://access.crunchydata.com/documentation/postgres-operator/latest/) and the Redis operator respectively. The nbe-operator creates the appropriate custom resources (e.g. `PostgresCluster`) and these operators run their own independent reconciliation loops to provision and manage the underlying clusters. This means database and cache lifecycle operations (failover, scaling, backups) are handled outside the nbe-operator's reconciliation cycle.

***

## Diagrams [#diagrams]

### Figure 1: Reconciliation Flow [#figure-1-reconciliation-flow]

<Mermaid
  chart="flowchart TD
    A[NetBoxEnterprise CR Changed] --> B[Watch / Event Queue]
    B --> C[Reconciliation Loop]
    C --> S{spec.suspend?}
    S -->|Yes| SP[Skip resource application]
    SP --> L[Await Next Change]
    S -->|No| D[Spec Validation]
    D --> E[License Cache Check]
    E --> F[External Secret Checksums]
    F --> G[Apply Resources in Order]
    G --> H[Component Status Check]
    H --> I{All Ready?}
    I -->|Yes| J[Set Ready=True]
    I -->|No| K[Requeue]
    J --> L
    K --> C"
/>

### Figure 2: Component Topology [#figure-2-component-topology]

<Mermaid
  chart="graph LR
    subgraph Operator[&#x22;nbe-operator&#x22;]
        OP[Operator Pod]
    end

    subgraph Ingress[&#x22;Edge Routing&#x22;]
        IG[Gateway / Ingress Controller]
    end

    subgraph NetBox[&#x22;NetBox Stack&#x22;]
        NB[NetBox App<br/>Deployment]
        NW[NetBox Worker<br/>Deployment]
    end

    subgraph Database[&#x22;Database Layer&#x22;]
        PGO[PGO<br/>Crunchy Postgres Operator]
        PG[PostgreSQL<br/>Cluster]
    end

    subgraph Cache[&#x22;Cache Layer&#x22;]
        ROP[Redis Operator]
        RD[Redis<br/>Cluster]
    end

    subgraph Diode[&#x22;Diode Stack (optional)&#x22;]
        DI[Ingester]
        DR[Reconciler]
        DA[Auth]
        HY[Hydra OIDC]
    end

    OP -->|reconciles| NB
    OP -->|reconciles| NW
    OP -->|creates CR| PGO
    OP -->|creates CR| ROP
    OP -->|reconciles| DI
    OP -->|reconciles| DR
    OP -->|reconciles| DA
    OP -->|reconciles| HY

    PGO -->|reconciles| PG
    ROP -->|reconciles| RD

    IG --> NB
    NB --> PG
    NB --> RD
    NW --> PG
    NW --> RD
    DI --> RD
    DR --> RD
    DR --> PG
    DR -->|NetBox API| NB
    DA --> HY
    HY --> PG"
/>