Docs
HelmInstallation

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 version

OpenShift

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-v2 SCC. Do not create a custom SCC or grant anyuid. The operator detects OpenShift when spec.platform is auto, which is the default. If a higher-priority SCC admits the pods without assigning a UID or fsGroup, the operator sets both itself and reports it in the SccIdentityAdvisory status 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. Leave gateway.enabled at 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: true and netboxEnterprise.spec.idp.enabled: true, Keycloak is not deployed. The IdentityProvider condition is False with reason PendingHost, and Ready can still be True. 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

ToolMinimum VersionPurpose
Helm3.xChart installation and management
kubectlMatching cluster versionCluster interaction and debugging

Resource Requirements

Cluster Sizing

EnvironmentvCPUMemory (RAM)Disk Space
Production (recommended)8 vCPU24 GB100 GB SSD
Non-production (minimum)4 vCPU16 GB50 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.

ComponentCPU RequestMemory RequestCPU LimitMemory Limit
Operator100m128Mi500m512Mi
NetBox app (per replica)200m750Mi1000m1500Mi
NetBox worker (per replica)100m128Mi1000m1500Mi
PostgreSQL (PGO-managed)N/AN/AN/AN/A
Redis250m256MiN/AN/A

For Diode components (if enabled):

ComponentCPU RequestMemory RequestCPU LimitMemory Limit
Reconciler100m256Mi500m512Mi
Ingester100m256Mi500m512Mi
Auth50m128Mi200m256Mi
Hydra100m256Mi500m512Mi

For the identity stack (Keycloak needs idp.enabled: true and netboxEnterprise.spec.idp.enabled: true):

ComponentCPU RequestMemory RequestCPU LimitMemory Limit
Keycloak (per instance)None1700MiNone2Gi
Keycloak realm-import Job (while it runs)None1700MiNone2Gi
Keycloak operator300m450Mi700m450Mi
PAS (per instance, if netboxEnterprise.spec.pas.enabled)100m128Mi500m256Mi
PAS migrate Job (while it runs)100m128Mi500m256Mi
Platform UI (per component, if netboxEnterprise.spec.ui.enabled)50m64Mi200m256Mi

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):

DependencyVersionPurposeToggle
PGO (Crunchy Postgres Operator)6.0.2Manages internal PostgreSQLpgo.enabled
Redis Operator0.25.0 chart, v0.26.0 imageManages internal Redisredis-operator.enabled
Replicated SDK1.19.12License managementreplicated.enabled
Traefik (subchart alias gateway)40.2.0Bundled Gateway API controller, disabled by default for Helm installsgateway.enabled
Keycloak Operator2.3.0 chart, 26.7.0 operatorManages the bundled Keycloak identity provider, disabled by default. Needs the netbox-enterprise-crds-keycloak chartidp.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-namespace

The 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): Creates ClusterRole and ClusterRoleBinding. The operator watches for NetBoxEnterprise resources across all namespaces.
  • namespace: Creates Role and RoleBinding in 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 groupResourcesVerbsWhen
apiextensions.k8s.iocustomresourcedefinitionsallAlways
apiextensions.k8s.iocustomresourcedefinitions/status, for netboxenterprises.netboxlabs.com onlyget, patch, updateAlways
netboxlabs.comnetboxenterprises, netboxenterprises/status, netboxenterprises/finalizersallAlways
netboxlabs.comgarageclusters, garageclusters/statuscreate, get, list, patch, update, watchAlways
deuxfleurs.frgaragenodescreate, get, list, patch, update, watchAlways
postgres-operator.crunchydata.compostgresclusters, postgresclusters/status, postgresclusters/finalizersallpgo.enabled
redis.redis.opstreelabs.inredis, redisclusters, redisreplications, redissentinels, and the /status and /finalizers subresource of eachallredis-operator.enabled
""namespacescreate, get, list, patch, update, watchAlways
""pods, services, configmaps, secrets, persistentvolumeclaims, serviceaccountsallAlways
""pods/statuspatchAlways
""pods/loggetAlways
""eventscreate, patchAlways
""nodeslistAlways
events.k8s.ioeventscreate, patchAlways
discovery.k8s.ioendpointsliceslistAlways
coordination.k8s.ioleasescreateAlways
coordination.k8s.ioleases, for nbe-operator-leader onlyget, patch, updateAlways
appsdeployments, statefulsets, replicasetsallAlways
batchjobs, cronjobsallAlways
rbac.authorization.k8s.ioroles, rolebindingsallAlways
networking.k8s.ioingresses, networkpoliciesallAlways
gateway.networking.k8s.iogateways, httproutes, grpcroutes, referencegrants, and backendtlspolicies (new in 2.5.0)allAlways
k8s.keycloak.orgkeycloaks, keycloaks/status, keycloakrealmimports (new in 2.5.0)allAlways
security.openshift.iopodsecuritypolicysubjectreviews (new in 2.5.0)createAlways
""endpoints/restricted (new in 2.5.0)createAlways
traefik.iomiddlewaresallAlways
embeddedcluster.replicated.cominstallationslistAlways
velero.iorestoresget, listAlways

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.yaml

Replace 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

On this page