Namespace-Scoped Installation
Install NetBox Enterprise with rbac.scope: namespace: the one-time cluster-admin steps, the features it disables, and how to verify the install
Installation Journey Prerequisites → Standard Installation → Namespace-Scoped Installation (you are here)
With rbac.scope: namespace, the netbox-enterprise chart gives the operator a Role and RoleBinding in the release namespace instead of a ClusterRole. The operator then watches only that namespace. This page covers the steps that still need a cluster admin, what the operator cannot do with a namespaced Role, and how to check that the install came up correctly.
The supported shape is a one-time setup by a cluster admin, after which the install holds no cluster-scoped rights. PostgreSQL and Redis run outside the chart, as external services.
Namespace-scoped installs need NetBox Enterprise 2.5.0 or later. Embedded Cluster installs are always cluster-scoped.
What changes
- One namespace. The operator reconciles only the
NetBoxEnterpriseresource in its own release namespace. It ignores resources in any other namespace. To run a second install, give it its own namespace and its own Helm release. - No cluster-scoped access. The operator's
Rolegrants nothing outside the release namespace. The operator does not try the reads thatRoledenies. It skips them and runs without the features they support. The next section lists those features. - No cluster-scoped install in the same cluster. A cluster-scoped NetBox Enterprise operator watches every namespace, so it also reconciles the
NetBoxEnterpriseresource of each namespace-scoped install. The two operators then overwrite each other's status: for example,ClusterScopedFeatureschanges betweenTrueandFalseas each one writes it. Do not run a namespace-scoped install in a cluster that also has a cluster-scoped NetBox Enterprise install. - A cluster admin owns the CRDs. The operator cannot read CRDs in namespace scope. At startup it checks that the
NetBoxEnterpriseCRD servesv1alpha2by listingnetboxenterprisesin its own namespace, and exits if it does not.
What you give up
The operator reports these on the NetBoxEnterprise resource, in the ClusterScopedFeatures condition, by the names in the first column. Each one needs cluster-scoped or cross-namespace access that the namespaced Role does not grant.
| Feature | What happens in namespace scope | What to do instead |
|---|---|---|
| Velero restore detection | The operator does not read Velero Restore objects or the Embedded Cluster restore state. For an object that carries a Velero restore label, it judges whether the restore is still running from the object's creation time instead. It also does not check the Velero restore plugin config, so the VeleroRestoreConfigInvalid condition never appears. | Check the plugin config yourself before you rely on a restore. See Velero restore plugin config. |
| cross-namespace ReferenceGrants | When a Gateway listener uses a certificate Secret in another namespace, the operator does not create the ReferenceGrant there. It logs a warning while your Gateway controller reports that listener's certificate reference as not permitted, and stops once a grant resolves it. The listener does not serve until the grant exists. | Keep the certificate Secret in the release namespace, or have someone with access to the other namespace create the grant. |
| node-count auto-scaling and hard topology spread | The operator cannot count nodes, so a replica count left at 0 (auto) resolves to 1 on a new install. In-cluster PostgreSQL and Redis on auto keep the count they already run, and other components on auto, such as the Diode services, drop to 1. The Redis and Garage one-pod-per-node spreads stay soft preferences. | Set each replica count you need explicitly. |
| host-environment telemetry | The custom metrics sent to Replicated omit the node count, CPU, and memory. | None needed. |
| the bundled Keycloak identity provider | The bundled Keycloak needs ClusterRoles. With spec.idp.enabled: true, the operator deploys no Keycloak and sets the IdentityProvider condition to False with reason NamespaceScopedUnsupported. | Use your own identity provider. See OIDC SSO. |
The operator also does not read the multi-node entitlement or the Embedded Cluster HA signal in namespace scope. Neither applies to a Helm install, so neither is on the condition. As a result, the MultiNodeNotEntitled condition does not appear.
One-time cluster-admin steps
A cluster admin does steps 1 to 3 before the install, and step 4 once an install runs 2.5.0 or later. Steps 1 and 3 are once per release namespace; steps 2 and 4 are once per cluster.
1. Create the release namespace
A namespace admin cannot create a namespace. A cluster admin creates it, and gives the installer the built-in admin role there. The example binds the user jane@example.com in netbox:
kubectl create namespace netbox
kubectl -n netbox create rolebinding netbox-installer-admin \
--clusterrole=admin --user=jane@example.com2. Install the CRD chart
CRDs are cluster-scoped, so a namespace admin cannot install them. A cluster admin installs netbox-enterprise-crds, at the same version as the netbox-enterprise chart you install. Install it into a namespace that only cluster admins can modify, never into the release namespace. The example uses a namespace named netbox-enterprise-crds:
kubectl create namespace netbox-enterprise-crds
helm install netbox-enterprise-crds \
oci://registry.enterprise.netboxlabs.com/netbox-enterprise/stable-v2/netbox-enterprise-crds \
--version 2.5.0 \
--namespace netbox-enterprise-crdsHelm records each release as a Secret in the namespace you install it into, here sh.helm.release.v1.netbox-enterprise-crds.v1. The installer's admin role can edit Secrets in the release namespace. On helm upgrade, Helm deletes every object in that stored record that the new chart no longer contains. It checks only the helm.sh/resource-policy: keep annotation, not who owns the object. So a tenant who could edit the record could make a cluster admin's next upgrade delete objects with cluster-admin rights. A tenant who deleted it would make that upgrade fail with has no deployed releases.
The CRDs are shared by every NetBox Enterprise install in the cluster. On each upgrade, a cluster admin upgrades this chart first, to the version you are upgrading to, with --namespace netbox-enterprise-crds in place of the release namespace. See Upgrading.
With external PostgreSQL and Redis, the install needs no other CRD chart.
If the CRD is missing, the operator exits at startup and logs NetBoxEnterprise CRD netboxenterprises.netboxlabs.com is not installed, or not yet Established. If the CRD chart is too old, it logs exists but does not serve version(s) v1alpha2.
3. Give the installer the permissions admin lacks
Do this once for each release namespace.
The installer needs the built-in admin role in the release namespace, plus two things admin does not include:
- Access to
NetBoxEnterpriseresources. The CRD does not extendadmin, so a namespace admin cannot create or read them. - Creating the operator's
Role. The chart creates aRolethat grants the operator access to NetBox Enterprise, Garage, Gateway API, and Keycloak resources, among others. Kubernetes refuses to let you create aRolethat grants permissions you do not hold yourself, so a namespace admin'shelm installfails withis attempting to grant RBAC permissions not currently held. Theescalateandbindverbs onRoles lift that check.
A cluster admin applies this Role and RoleBinding. The example binds the user jane@example.com in netbox:
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: netbox-enterprise-installer
namespace: netbox
rules:
- apiGroups: [rbac.authorization.k8s.io]
resources: [roles]
verbs: [escalate, bind]
- apiGroups: [netboxlabs.com]
resources: [netboxenterprises]
verbs: [get, list, watch, create, update, patch, delete]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: netbox-enterprise-installer
namespace: netbox
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: Role
name: netbox-enterprise-installer
subjects:
- apiGroup: rbac.authorization.k8s.io
kind: User
name: jane@example.comA Role grants access only inside its own namespace, so neither rule reaches another namespace. To bind a group, change the subject's kind to Group. To bind a CI service account, use kind: ServiceAccount with its name and namespace, and no apiGroup.
4. Run the storage-version migration once per cluster
A cluster-scoped operator moves every NetBoxEnterprise object to the v1alpha2 storage version at startup. A namespace-scoped operator cannot, because that means changing the CRD. A cluster admin runs a one-time Job that does it instead. Without it, a later CRD chart upgrade that stops serving v1alpha1 fails on this cluster.
Run it once per cluster, not once per install:
- after at least one install in the cluster runs NetBox Enterprise 2.5.0 or later, in a namespace that only cluster admins can modify;
- before you upgrade
netbox-enterprise-crdsto a release that stops servingv1alpha1.
The Job takes its operator image from that install and runs it with write access to every NetBoxEnterprise in the cluster. That is why the image must not come from a namespace a tenant can change.
The Job and its runbook ship inside the netbox-enterprise chart, under files/storage-version-migration/. Helm does not install them. Pull the chart version you have installed and follow README.md in that directory:
helm pull oci://registry.enterprise.netboxlabs.com/netbox-enterprise/stable-v2/netbox-enterprise \
--version 2.5.0 --untar
cd netbox-enterprise/files/storage-version-migrationThe runbook starts by checking whether the cluster needs the migration at all. Running it again is safe.
When every install is tenant-run
If every install in the cluster is namespace-scoped and run by a tenant, no install meets the condition above. Do not take the Job's image from a tenant's Deployment. Do one of these instead:
- Keep one install of your own. Run one install at 2.5.0 or later in a namespace that only cluster admins can modify, and point the runbook at it.
- Pin the operator image by digest from the registry.
helm show valueson your installed chart version prints the operator image underoperator.image. Resolve thatregistry/repository:tagto a digest yourself, from the registry you install from, with a tool such ascrane digest. Run the runbook's step 2 as written. Then set bothNBE_OPERATOR_IMAGEandNBE_OPERATOR_DIGESTto<registry>/<repository>@sha256:<digest>before the runbook's step 3. Its step 4 accepts that reference, and its step 5 checks that the Job ran that digest.
With the second option, the runbook's step 3 still copies the pull secrets from the install that its step 2 names. The digest fixes which build runs, so those secrets only authenticate the pull.
Install
With steps 1 to 3 done, the installer installs the chart in the release namespace. Follow Standard Installation, with these changes:
- In its step 1, use the values below as your values file.
- Skip its step 2, Create the Namespace. The cluster admin created it.
- Skip its step 5, Install CRDs. The cluster admin installed them.
- In its step 7, set
external: truefor bothpostgresqlandredisin anyNetBoxEnterprisemanifest you apply, with the same connection settings as the values file, includingrequireAuth: trueunderredis. Without it, the operator warns that the Redis password will be ignored. No shipped example manifest sets both. Apply it in the same namespace as the Helm release. - On OpenShift, which is in Private Preview, also add the OpenShift routing values.
Leave out the components that need cluster-scoped RBAC
Some components that the netbox-enterprise chart can install create cluster-scoped objects of their own, whatever rbac.scope says. An installer without cluster-admin rights cannot create them:
| Chart value | Component | Cluster-scoped objects it creates |
|---|---|---|
pgo.enabled (default true) | Crunchy Postgres Operator, for in-cluster PostgreSQL | ClusterRole and ClusterRoleBinding pgo |
redis-operator.enabled (default true) | Redis Operator, for in-cluster Redis | ClusterRole and ClusterRoleBinding redis-operator |
gateway.enabled (default false) | Bundled Traefik gateway | A ClusterRole, a ClusterRoleBinding, a GatewayClass, and an IngressClass |
idp.enabled (default false) | Keycloak operator, for the bundled identity provider | ClusterRoles and a ClusterRoleBinding |
For an install with no cluster-scoped objects, turn all four off. Use an external PostgreSQL and an external Redis, and route through your existing ingress controller. If you need any of the four, a cluster admin has to run the install.
Values for a namespace-scoped install
These values turn all four off and point both stores at external services. Set the hosts and Secret names to your own. Create the password Secrets in the release namespace first, as External PostgreSQL and External Redis describe.
rbac:
scope: namespace
pgo:
enabled: false
redis-operator:
enabled: false
gateway:
enabled: false
idp:
enabled: false
netboxEnterprise:
enabled: true
spec:
postgresqlProfiles:
netbox:
host: "postgres.example.com"
port: 5432
postgresql:
external: true
postgresqlProfile: netbox
redis:
external: true
requireAuth: true
netbox:
config:
postgres:
database: "netbox"
user: "netbox"
password:
name: netbox-db-credentials
key: password
redis:
host: "redis.example.com"
port: 6379
password:
name: redis-credentials
key: password
diode:
enabled: falserequireAuth: true tells the operator that the external Redis takes the password in netbox.config.redis.password. Without it, the operator logs a warning that the password will be ignored.
The example turns Diode off. Diode needs its own databases on the external PostgreSQL. To run it, set them up as External PostgreSQL describes.
To confirm that your values render nothing cluster-scoped, render them and list the kinds. This must print nothing:
helm template netbox-enterprise \
oci://registry.enterprise.netboxlabs.com/netbox-enterprise/stable-v2/netbox-enterprise \
--version 2.5.0 --namespace netbox --values netbox-values.yaml \
| grep -E '^kind: (Cluster|GatewayClass|IngressClass|CustomResourceDefinition)'On 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.
The values above set no host and no Ingress class, so on OpenShift the operator creates an Ingress for the nginx class, the router creates no Route, and NetBox is not reachable from outside the cluster. Add these values to route NetBox through the OpenShift router:
netboxEnterprise:
spec:
netbox:
urls:
- "https://netbox.apps.<cluster-domain>"
ingress:
className: openshift-default
tls:
- {}See On OpenShift for what each value does and how to check the route. Its CRD charts step does not apply here: a namespace-scoped install needs only netbox-enterprise-crds, which the cluster admin installed in Install the CRD chart.
Verify the install
Run these in the release namespace, here netbox. Each one says what a correct namespace-scoped install prints.
-
The chart created a
RoleandRoleBindingfor the operator:kubectl -n netbox get role,rolebinding netbox-enterprise -
The operator started in namespace scope. It logs this line once at startup, naming every disabled feature:
kubectl -n netbox logs deploy/netbox-enterprise -c operator | grep 'Namespace-scoped install' -
The API server refuses the operator nothing except
PostgresClusterreads. This prints0:kubectl -n netbox logs deploy/netbox-enterprise -c operator | grep -i forbidden | grep -vc postgresclustersWith
pgo.enabled: false, the chart does not grant the operator access toPostgresClusterresources, but the operator still tries to read one on each reconcile. It logs warnings such ascould not read the recovery state from the live PostgresCluster, with aforbiddenerror. This happens in both RBAC scopes, and with an external database there is noPostgresClusterfor it to read. -
The license loaded. The
LICENSEcolumn showsDev,Trial, orPaid, andLicenseHealthisTruewith reasonLicenseValid:kubectl -n netbox get netboxenterprises kubectl -n netbox get netboxenterprise netbox \ -o jsonpath='{.status.conditions[?(@.type=="LicenseHealth")].status} {.status.conditions[?(@.type=="LicenseHealth")].reason}{"\n"}'If
LicenseHealthisFalsewith reasonLicenseUnavailable, the operator cannot get a license from the Replicated SDK. Check that thereplicatedpod in the release namespace is running. The operator does not reconcile until it has a license. -
The resource reports namespace scope. This prints
False NamespaceScopedand the message below:kubectl -n netbox get netboxenterprise netbox \ -o jsonpath='{range .status.conditions[?(@.type=="ClusterScopedFeatures")]}{.status} {.reason}{"\n"}{.message}{"\n"}{end}'False NamespaceScoped Namespace-scoped RBAC (rbac.scope: namespace, watching only netbox) disables: Velero restore detection, cross-namespace ReferenceGrants, node-count auto-scaling and hard topology spread, host-environment telemetry, the bundled Keycloak identity provider. Each needs cluster-scoped or cross-namespace access the namespaced Role does not grant. -
The operator serves its metrics. In one terminal, forward the metrics port:
kubectl -n netbox port-forward deploy/netbox-enterprise 8080:8080In another, read a reconcile counter. It prints at least one
nbe_reconciliation_totalline:curl -s http://localhost:8080/metrics | grep '^nbe_reconciliation_total' -
The install is ready. This prints
True AllComponentsReady:kubectl -n netbox get netboxenterprise netbox \ -o jsonpath='{.status.conditions[?(@.type=="Ready")].status} {.status.conditions[?(@.type=="Ready")].reason}{"\n"}'
Replace netbox with your namespace, and netbox in netboxenterprise netbox with the name of your NetBoxEnterprise resource. The commands assume the Helm release is named netbox-enterprise, as in Standard Installation. For another release name, list the names to use with kubectl -n netbox get role,rolebinding,deploy -l app.kubernetes.io/instance=<release>. ClusterScopedFeatures is advisory: it never makes Ready false.
Create a ReferenceGrant
When a Gateway listener in the release namespace uses a certificate Secret from another namespace, someone with access to that namespace creates this grant there. The example lets Gateways in netbox read the Secret netbox-tls in certs:
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
name: netbox-gateway-tls-grant
namespace: certs
spec:
from:
- group: gateway.networking.k8s.io
kind: Gateway
namespace: netbox
to:
- group: ""
kind: Secret
name: netbox-tlsTo find the Secrets that need a grant, read the operator's warning:
kubectl -n netbox logs deploy/netbox-enterprise -c operator | grep 'cannot grant'The operator reads the status of its own Gateways. It logs this warning only while a listener reports ResolvedRefs=False with reason RefNotPermitted, and stops once the grant resolves the reference:
A Gateway listener's certificate in another namespace is not permitted (ResolvedRefs=False, RefNotPermitted), and a namespace-scoped operator cannot grant it; for each listed namespace/secret, create a ReferenceGrant in that namespace allowing Gateways from this one to reference the SecretIts secrets field lists each certificate Secret behind a refused listener, as namespace/secret. Its listeners field lists the refused listeners. The warning relies on your Gateway controller writing listener status, so with no controller running it never appears. If the operator cannot read the Gateway status, it logs Could not read Gateway status to check for a missing ReferenceGrant instead.
Switching scope
rbac.scope is a value of the netbox-enterprise chart, so helm upgrade changes it. Both directions need a cluster admin.
Moving from namespace to cluster needs a cluster admin, because the chart then creates a ClusterRole and ClusterRoleBinding. After the switch, the operator does the disabled work again, and ClusterScopedFeatures changes to True with reason ClusterScoped.
Moving from cluster to namespace needs a cluster admin, because Helm must delete the operator's ClusterRole and ClusterRoleBinding. If a namespace installer runs helm upgrade --set rbac.scope=namespace, Helm cannot read those two objects. It skips any object it cannot read and still reports success (checked in Helm 3.19.0 and 4.3.0). The operator's ServiceAccount then keeps its cluster-wide grants, and anyone who can create pods in the release namespace can run a pod as that ServiceAccount and use them. ClusterScopedFeatures still reports False NamespaceScoped, because it reads the namespace the operator watches, not the RBAC bound to it.
So a cluster admin runs that upgrade, or deletes the two objects after it. Then the cluster admin checks that both are gone. This must print NotFound for both:
kubectl get clusterrole,clusterrolebinding netbox-enterpriseWith the release named netbox-enterprise, as in Standard Installation, both objects have that name. The namespace installer gets Forbidden from this command, so the check has to be the cluster admin's.
Moving to namespace also takes the features in What you give up away from a running install. Check these first:
- A bundled Keycloak is removed.
- Components on auto replica counts, other than in-cluster PostgreSQL and Redis, drop to
1. ReferenceGrants the operator created in other namespaces stay behind. Delete them by hand if you no longer need them.- Turning off
pgoorredis-operatorremoves the operator that runs an in-cluster database. Move to external PostgreSQL and Redis before you turn them off.
See also
- Security: both RBAC scopes
- Status & Conditions: the
ClusterScopedFeaturescondition - Upgrading: CRD chart upgrades