Prerequisites
System requirements, tooling, and access needed before installing NetBox Enterprise
Installation Journey Prerequisites (you are here) → Quickstart or Standard Install → Configure
Before installing NetBox Enterprise with the netbox-enterprise Helm chart, verify your environment meets these requirements.
Kubernetes Version
The nbe-operator chart requires Kubernetes 1.33 or later. Every chart declares kubeVersion: ">=1.33.0-0", so Helm refuses to install on anything older and sets no upper bound.
kubectl versionOpenShift
Private Preview
OpenShift support is in Private Preview in NetBox Enterprise 2.5.0. Contact Customer Support for OpenShift deployments. More OpenShift support work is planned for later releases.
NetBox Enterprise 2.5.0 installs on OpenShift with the Helm chart. Treat an OpenShift install as pre-production while OpenShift support is in Private Preview. An OpenShift install has these requirements:
- Version: OpenShift 4.20 or later. OpenShift 4.20 ships Kubernetes 1.33, the minimum version the charts accept. On OpenShift 4.19 and earlier, Helm stops with
chart requires kubeVersion. - Security context constraints (SCCs): every pod runs under the default
restricted-v2SCC. Do not create a custom SCC or grantanyuid. The operator detects OpenShift whenspec.platformisauto, which is the default. If a higher-priority SCC admits the pods without assigning a UID orfsGroup, the operator sets both itself and reports it in theSccIdentityAdvisorystatus condition. - Cluster access: the steps on this page and in Install on OpenShift assume a cluster administrator runs the install. For a team without standing cluster-admin access, see Namespace-Scoped Installation.
- Gateway API CRDs: do not install
netbox-enterprise-crds-gateway. OpenShift ships and manages the Gateway API CRDs itself. Leavegateway.enabledat its default,false. - Routing: the default Ingress class,
nginx, does not exist on OpenShift. Route NetBox through the OpenShift router instead. See Install on OpenShift for the values. - Bundled Keycloak: not available on OpenShift in 2.5.0. Keycloak needs Gateway routing, and OpenShift installs route through Ingress. With
idp.enabled: trueandnetboxEnterprise.spec.idp.enabled: true, Keycloak is not deployed. TheIdentityProvidercondition isFalsewith reasonPendingHost, andReadycan still beTrue. Leave the bundled Keycloak off on OpenShift.
NetBox Labs tested the 2.5.0 Helm install on OKD and on OpenShift Container Platform 4.22 (Kubernetes 1.35) with LVM Storage (LVMS). High availability, Red Hat OpenShift Service on AWS (ROSA), Azure Red Hat OpenShift (ARO), and disconnected clusters are not tested on OpenShift in 2.5.0.
Required Tools
| Tool | Minimum Version | Purpose |
|---|---|---|
| Helm | 3.x | Chart installation and management |
| kubectl | Matching cluster version | Cluster interaction and debugging |
Resource Requirements
Cluster Sizing
| Environment | vCPU | Memory (RAM) | Disk Space |
|---|---|---|---|
| Production (recommended) | 8 vCPU | 24 GB | 100 GB SSD |
| Non-production (minimum) | 4 vCPU | 16 GB | 50 GB SSD |
These recommendations account for the full stack: operator, NetBox application, workers, PostgreSQL, Redis, and Diode components. SSD or NVMe storage is recommended for database performance.
These recommendations do not include the identity stack. If you turn on any part of the identity stack, add its memory requests from Per-Component Defaults.
Per-Component Defaults
The chart ships with the following resource defaults. These are starting points; production deployments should allocate resources based on the cluster sizing above.
| Component | CPU Request | Memory Request | CPU Limit | Memory Limit |
|---|---|---|---|---|
| Operator | 100m | 128Mi | 500m | 512Mi |
| NetBox app (per replica) | 200m | 750Mi | 1000m | 1500Mi |
| NetBox worker (per replica) | 100m | 128Mi | 1000m | 1500Mi |
| PostgreSQL (PGO-managed) | N/A | N/A | N/A | N/A |
| Redis | 250m | 256Mi | N/A | N/A |
For Diode components (if enabled):
| Component | CPU Request | Memory Request | CPU Limit | Memory Limit |
|---|---|---|---|---|
| Reconciler | 100m | 256Mi | 500m | 512Mi |
| Ingester | 100m | 256Mi | 500m | 512Mi |
| Auth | 50m | 128Mi | 200m | 256Mi |
| Hydra | 100m | 256Mi | 500m | 512Mi |
For the identity stack (Keycloak needs idp.enabled: true and netboxEnterprise.spec.idp.enabled: true):
| Component | CPU Request | Memory Request | CPU Limit | Memory Limit |
|---|---|---|---|---|
| Keycloak (per instance) | None | 1700Mi | None | 2Gi |
| Keycloak realm-import Job (while it runs) | None | 1700Mi | None | 2Gi |
| Keycloak operator | 300m | 450Mi | 700m | 450Mi |
PAS (per instance, if netboxEnterprise.spec.pas.enabled) | 100m | 128Mi | 500m | 256Mi |
| PAS migrate Job (while it runs) | 100m | 128Mi | 500m | 256Mi |
Platform UI (per component, if netboxEnterprise.spec.ui.enabled) | 50m | 64Mi | 200m | 256Mi |
By default, a cluster runs as many Keycloak instances and as many PAS instances as it has nodes, to a maximum of three. netboxEnterprise.spec.idp.replicas and netboxEnterprise.spec.pas.replicas set a different count. The Platform UI runs one shell and a maximum of eight remotes, one pod each. With every part on, the identity stack requests approximately 2.8Gi of memory on one node. While its Jobs run, the identity stack requests approximately 4.6Gi. Each further node that runs a Keycloak instance and a PAS instance needs approximately 1.8Gi for them.
The per-component defaults are conservative requests to allow scheduling. For production workloads, ensure your nodes have sufficient headroom above these minimums; the cluster sizing recommendations above should be used as the target.
Registry Access
NetBox Enterprise is distributed through NetBox Labs' Replicated registries: the Helm charts are pulled from registry.enterprise.netboxlabs.com and the container images from proxy.enterprise.netboxlabs.com. Authenticate to the chart registry with your license credentials (your email as the username and your license ID as the password) before installing - the Quickstart and Standard Installation both begin with a helm registry login step.
You do not need to create an image-pull secret by hand. The bundled Replicated SDK provisions the netbox-enterprise-helm-registry pull secret at install time, so every component - including Redis - can pull its image from the proxy registry.
To pull images from your own private registry instead, see Private Registry.
Chart Dependencies
The netbox-enterprise chart automatically installs these dependencies (can be disabled individually):
| Dependency | Version | Purpose | Toggle |
|---|---|---|---|
| PGO (Crunchy Postgres Operator) | 6.0.2 | Manages internal PostgreSQL | pgo.enabled |
| Redis Operator | 0.25.0 chart, v0.26.0 image | Manages internal Redis | redis-operator.enabled |
| Replicated SDK | 1.19.12 | License management | replicated.enabled |
Traefik (subchart alias gateway) | 40.2.0 | Bundled Gateway API controller, disabled by default for Helm installs | gateway.enabled |
| Keycloak Operator | 2.3.0 chart, 26.7.0 operator | Manages the bundled Keycloak identity provider, disabled by default. Needs the netbox-enterprise-crds-keycloak chart | idp.enabled |
The Redis Operator chart and image versions differ on purpose. 0.25.0 is the newest chart upstream publishes, and the operator image is pinned ahead of it to v0.26.0, which carries the fix for one unpullable Redis pod stalling master election.
Gateway API CRDs (Gateway Routing Only)
The operator routes external traffic through the Kubernetes Gateway API when gateway routing is enabled in the CR (spec.gateway) and the Gateway API CRDs are present, and falls back to Ingress resources otherwise (see Routing Mode). If you enable the bundled Traefik controller (gateway.enabled: true), install the netbox-enterprise-crds-gateway chart before the main chart:
helm install netbox-enterprise-crds-gateway \
oci://registry.enterprise.netboxlabs.com/netbox-enterprise/stable-v2/netbox-enterprise-crds-gateway \
--version 2.5.0 \
--namespace netbox --create-namespaceThe chart vendors the Gateway API v1.5.1 standard CRDs. Skip it if you bring your own Gateway API controller (your cluster already has the CRDs) or stay on the Ingress path. Skip it on OpenShift, which ships and manages the Gateway API CRDs itself. Embedded Cluster installs it automatically.
The upload-size cap (spec.gateway.maxRequestBodyBytes) is enforced through a Traefik Middleware, which needs the traefik.io CRDs. Embedded Cluster ships them automatically via the netbox-enterprise-crds-traefik chart. On Helm with the bundled Traefik controller, install that chart too if you want the cap enforced -- without it the operator skips the Middleware (no cap) and logs a warning. Bring-your-own gateways manage their own traefik.io CRDs.
When using an external PostgreSQL database, you can disable PGO with pgo.enabled: false. Similarly, set redis-operator.enabled: false when using external Redis. See the Configuration section for details.
RBAC Requirements
The operator requires cluster-level or namespace-level RBAC permissions depending on the rbac.scope setting:
cluster(default): CreatesClusterRoleandClusterRoleBinding. The operator watches forNetBoxEnterpriseresources across all namespaces.namespace: CreatesRoleandRoleBindingin the release namespace only. The operator watches only the namespace where it is installed. A cluster admin still has to install the CRDs and run some one-time steps, and some features are disabled. See Namespace-Scoped Installation.
Rules the operator needs
The table lists every rule in the ClusterRole that the 2.5.0 netbox-enterprise chart creates. The 2.3.0 and 2.4.0 charts create the same rules, except the ones marked new in 2.5.0. The chart creates it only when operator.enabled and rbac.create are true and rbac.scope is cluster. A rule marked Always is in every ClusterRole install (rbac.scope: cluster). With rbac.scope: namespace, the chart creates a Role that leaves some of those rules out, as the paragraph after the table explains. A conditional rule is in the role only when the named Helm value is true.
In the Verbs column, all means create, delete, get, list, patch, update and watch. An empty API group cell ("") is the core API group.
| API group | Resources | Verbs | When |
|---|---|---|---|
apiextensions.k8s.io | customresourcedefinitions | all | Always |
apiextensions.k8s.io | customresourcedefinitions/status, for netboxenterprises.netboxlabs.com only | get, patch, update | Always |
netboxlabs.com | netboxenterprises, netboxenterprises/status, netboxenterprises/finalizers | all | Always |
netboxlabs.com | garageclusters, garageclusters/status | create, get, list, patch, update, watch | Always |
deuxfleurs.fr | garagenodes | create, get, list, patch, update, watch | Always |
postgres-operator.crunchydata.com | postgresclusters, postgresclusters/status, postgresclusters/finalizers | all | pgo.enabled |
redis.redis.opstreelabs.in | redis, redisclusters, redisreplications, redissentinels, and the /status and /finalizers subresource of each | all | redis-operator.enabled |
"" | namespaces | create, get, list, patch, update, watch | Always |
"" | pods, services, configmaps, secrets, persistentvolumeclaims, serviceaccounts | all | Always |
"" | pods/status | patch | Always |
"" | pods/log | get | Always |
"" | events | create, patch | Always |
"" | nodes | list | Always |
events.k8s.io | events | create, patch | Always |
discovery.k8s.io | endpointslices | list | Always |
coordination.k8s.io | leases | create | Always |
coordination.k8s.io | leases, for nbe-operator-leader only | get, patch, update | Always |
apps | deployments, statefulsets, replicasets | all | Always |
batch | jobs, cronjobs | all | Always |
rbac.authorization.k8s.io | roles, rolebindings | all | Always |
networking.k8s.io | ingresses, networkpolicies | all | Always |
gateway.networking.k8s.io | gateways, httproutes, grpcroutes, referencegrants, and backendtlspolicies (new in 2.5.0) | all | Always |
k8s.keycloak.org | keycloaks, keycloaks/status, keycloakrealmimports (new in 2.5.0) | all | Always |
security.openshift.io | podsecuritypolicysubjectreviews (new in 2.5.0) | create | Always |
"" | endpoints/restricted (new in 2.5.0) | create | Always |
traefik.io | middlewares | all | Always |
embeddedcluster.replicated.com | installations | list | Always |
velero.io | restores | get, list | Always |
The table covers only the operator's own role. With idp.enabled: true, the keycloak-operator subchart adds RBAC of its own for the Keycloak operator: five ClusterRoles, a ClusterRoleBinding, a Role and six RoleBindings. rbac.create and rbac.scope do not control them.
The operator needs the garageclusters and garagenodes rules even when in-cluster object storage is off. It reads garageclusters on every reconcile to find a Garage store left over from an earlier configuration.
With rbac.scope: namespace, the chart creates a Role instead, from templates/role.yaml. It holds the namespaced rules from the table and leaves out the cluster-scoped ones, such as customresourcedefinitions, namespaces and nodes.
Managing RBAC yourself
If you set rbac.create: false, the chart creates no role for the operator, and you must give the operator's ServiceAccount the rules above yourself. The keycloak-operator subchart still creates its own RBAC when idp.enabled is true. Do not copy the rules from the chart defaults. The conditional rules depend on your values, so render the role from the values file you install with:
REGISTRY=oci://registry.enterprise.netboxlabs.com/netbox-enterprise/stable-v2
VERSION=2.5.0
# rbac.create=true here only makes the template render; it does not change your install.
helm template netbox-enterprise "$REGISTRY/netbox-enterprise" \
--version "$VERSION" --namespace netbox \
--values my-values.yaml \
--set rbac.create=true \
--show-only templates/clusterrole.yamlReplace my-values.yaml with your own values file. For rbac.scope: namespace, render templates/role.yaml instead. Render the role again for each new chart version before you upgrade, because a release can add rules.
Persistent Storage
The cluster must have a default StorageClass or you must specify one explicitly. Storage is used for:
- PostgreSQL data (default: 4Gi)
- NetBox media files (default: 10Gi)
- NetBox scripts (default: 1Gi)
- Redis persistence (if enabled)
External Storage
For production deployments, consider using external managed services (e.g., AWS RDS for PostgreSQL, ElastiCache for Redis) instead of in-cluster storage. See PostgreSQL Configuration and Redis Configuration for external database setup.
Next Steps
- Quickstart: Get running in 5 minutes with minimal configuration
- Standard Installation: Full installation with custom values