Docs
HelmInstallation

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 NetBoxEnterprise resource 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 Role grants nothing outside the release namespace. The operator does not try the reads that Role denies. 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 NetBoxEnterprise resource of each namespace-scoped install. The two operators then overwrite each other's status: for example, ClusterScopedFeatures changes between True and False as 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 NetBoxEnterprise CRD serves v1alpha2 by listing netboxenterprises in 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.

FeatureWhat happens in namespace scopeWhat to do instead
Velero restore detectionThe 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 ReferenceGrantsWhen 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 spreadThe 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 telemetryThe custom metrics sent to Replicated omit the node count, CPU, and memory.None needed.
the bundled Keycloak identity providerThe 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.com

2. 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-crds

Helm 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 NetBoxEnterprise resources. The CRD does not extend admin, so a namespace admin cannot create or read them.
  • Creating the operator's Role. The chart creates a Role that grants the operator access to NetBox Enterprise, Garage, Gateway API, and Keycloak resources, among others. Kubernetes refuses to let you create a Role that grants permissions you do not hold yourself, so a namespace admin's helm install fails with is attempting to grant RBAC permissions not currently held. The escalate and bind verbs on Roles 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.com

A 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-crds to a release that stops serving v1alpha1.

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-migration

The 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 values on your installed chart version prints the operator image under operator.image. Resolve that registry/repository:tag to a digest yourself, from the registry you install from, with a tool such as crane digest. Run the runbook's step 2 as written. Then set both NBE_OPERATOR_IMAGE and NBE_OPERATOR_DIGEST to <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:

  1. In its step 1, use the values below as your values file.
  2. Skip its step 2, Create the Namespace. The cluster admin created it.
  3. Skip its step 5, Install CRDs. The cluster admin installed them.
  4. In its step 7, set external: true for both postgresql and redis in any NetBoxEnterprise manifest you apply, with the same connection settings as the values file, including requireAuth: true under redis. 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.
  5. 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 valueComponentCluster-scoped objects it creates
pgo.enabled (default true)Crunchy Postgres Operator, for in-cluster PostgreSQLClusterRole and ClusterRoleBinding pgo
redis-operator.enabled (default true)Redis Operator, for in-cluster RedisClusterRole and ClusterRoleBinding redis-operator
gateway.enabled (default false)Bundled Traefik gatewayA ClusterRole, a ClusterRoleBinding, a GatewayClass, and an IngressClass
idp.enabled (default false)Keycloak operator, for the bundled identity providerClusterRoles 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: false

requireAuth: 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.

  1. The chart created a Role and RoleBinding for the operator:

    kubectl -n netbox get role,rolebinding netbox-enterprise
  2. 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'
  3. The API server refuses the operator nothing except PostgresCluster reads. This prints 0:

    kubectl -n netbox logs deploy/netbox-enterprise -c operator | grep -i forbidden | grep -vc postgresclusters

    With pgo.enabled: false, the chart does not grant the operator access to PostgresCluster resources, but the operator still tries to read one on each reconcile. It logs warnings such as could not read the recovery state from the live PostgresCluster, with a forbidden error. This happens in both RBAC scopes, and with an external database there is no PostgresCluster for it to read.

  4. The license loaded. The LICENSE column shows Dev, Trial, or Paid, and LicenseHealth is True with reason LicenseValid:

    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 LicenseHealth is False with reason LicenseUnavailable, the operator cannot get a license from the Replicated SDK. Check that the replicated pod in the release namespace is running. The operator does not reconcile until it has a license.

  5. The resource reports namespace scope. This prints False NamespaceScoped and 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.
  6. The operator serves its metrics. In one terminal, forward the metrics port:

    kubectl -n netbox port-forward deploy/netbox-enterprise 8080:8080

    In another, read a reconcile counter. It prints at least one nbe_reconciliation_total line:

    curl -s http://localhost:8080/metrics | grep '^nbe_reconciliation_total'
  7. 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-tls

To 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 Secret

Its 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-enterprise

With 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 pgo or redis-operator removes the operator that runs an in-cluster database. Move to external PostgreSQL and Redis before you turn them off.

See also

On this page