Installation

This guide covers the complete installation process for NetBox Enterprise using Helm on Kubernetes.

Quick Start

For a quick installation in a clean Kubernetes cluster, the chart's default values often work without modification:

# After authentication and pulling the values file (see steps below)
helm install netbox-enterprise \
  oci://registry.netboxlabs.com/netbox-enterprise/beta/netbox-enterprise \
  --namespace netbox-enterprise \
  --create-namespace \
  --values netbox-enterprise-values.yaml \
  --version 1.11.4

The chart includes everything needed for a functional deployment, including an NGINX Ingress Controller, databases, and all required components.

Prerequisites

Before starting installation:

• Ensure you meet all prerequisites
• Have your NetBox Enterprise license information ready
• Access to container registries
• Kubernetes cluster admin access

Authentication and Registry Setup

NetBox Enterprise requires authentication to access the container registry and Helm chart. You'll need your username and license ID provided by NetBox Labs.

Step 1: Set License Variables

# Set your credentials
export USERNAME="your-email@company.com"
export SERVICE_ACCOUNT_TOKEN="your-service-account-token-here"

# Verify they are set
echo "Username: $USERNAME"
echo "Service Account Token: $SERVICE_ACCOUNT_TOKEN"

Step 2: Log in to the Registries

# Log in to the Docker registry (for authentication)
docker login proxy.replicated.com -u $USERNAME -p $SERVICE_ACCOUNT_TOKEN

# Log in to the OCI registry for Helm charts
helm registry login registry.replicated.com -u $USERNAME -p $SERVICE_ACCOUNT_TOKEN

Note: Docker images are pulled from proxy.enterprise.netboxlabs.com but authentication is done against proxy.replicated.com

Step 3: Pull the Values File

You must pull the existing values file from the registry, which contains your license information and required configurations:

# Pull the default values file with your license data
helm show values oci://registry.replicated.com/netbox-enterprise/beta/netbox-enterprise \
  --version 1.11.4 > netbox-enterprise-values.yaml

Important: Do not create a values file from scratch. The pulled values file contains critical license signatures and configurations required for the application to function correctly.

Step 4: Edit the Values File

Now edit the netbox-enterprise-values.yaml file to configure your deployment. See the Configuration section for details on available options.

Standard Installation

Download and Customize Values

# Download the base values template
curl -O https://netboxlabs.com/docs/files/values-extra.yaml

# Edit the values file for your environment
vim values-extra.yaml

Install Commands

# Standard installation
helm install netbox-enterprise \
  oci://registry.netboxlabs.com/netbox-enterprise/beta/netbox-enterprise \
  --values netbox-enterprise-values.yaml \
  --values values-extra.yaml \
  --version 1.11.4 \
  --create-namespace \
  --namespace netbox-enterprise \
  --wait \
  --timeout 10m

Installation Options

• --wait: Wait until deployment is ready
• --timeout: Maximum time to wait for deployment
• --debug: Enable debug output for troubleshooting
• --dry-run: Preview what would be installed

Configuration Options

External Database Configuration

For production deployments using external PostgreSQL:

Create External Database Secrets

When using an external PostgreSQL, you need to create 3 secrets, one each for NetBox, Diode, and Hydra.

You will need to know the URI for each database (eg, postgres://user:password@host:port/dbname). Also note, if the password contains special characters, you will need to URL-encode it. You can use a tool like jq (or anything else that supports URL-encoding like trurl) to do so.

printf '%s' '<your_password>' | jq -sRr '@uri'

For each database, run kubectl to create the secret:

kubectl create secret generic nbe-external-database-secret-netbox --from-literal=uri='<netbox_db_uri>'
kubectl create secret generic nbe-external-database-secret-diode --from-literal=uri='<diode_db_uri>'
kubectl create secret generic nbe-external-database-secret-hydra --from-literal=uri='<hydra_db_uri>'

External Database Override File

Download the external database configuration template:

curl -O https://netboxlabs.com/docs/files/external-database-values.yaml

If you choose different secret names than the examples above, you will need to edit this file and change the secrets to match.

Then, when running helm install or helm upgrade, add --values path/to/external-database-values.yaml to the end of the command. The helm command supports passing --values multiple times, and each subsequent values file overlays on top of previous ones.

Custom Ingress Configuration

Configure ingress for your environment:

# Add to your values file
ingress:
  enabled: true
  className: "nginx"
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
  hosts:
    - host: netbox.company.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: netbox-tls
      hosts:
        - netbox.company.com

Installation Process

Pre-flight Checks

Install and run preflight checks to validate your cluster:

# Install preflight plugin
curl https://krew.sh/preflight | bash

# Run preflight checks
helm template ./netbox-enterprise-1.11.4.tgz | kubectl preflight -

Install Commands

# Standard installation with custom values
helm install netbox-enterprise \
  oci://registry.netboxlabs.com/netbox-enterprise/beta/netbox-enterprise \
  --values netbox-enterprise-values.yaml \
  --values values-extra.yaml \
  --version 1.11.4 \
  --create-namespace \
  --namespace netbox-enterprise

# For installations in environments with restricted connectivity
helm install netbox-enterprise ./netbox-enterprise-1.11.4.tgz \
  --values netbox-enterprise-values.yaml \
  --values values-extra.yaml \
  --values my-private-registry.yaml \
  --create-namespace \
  --namespace netbox-enterprise

Verify Installation

After running the installation commands, verify your deployment:

Check Pod Status

# View all pods
kubectl get pods -n netbox-enterprise

# Expected output should show all pods as Running
# Example output:
# NAME                                     READY   STATUS    RESTARTS   AGE
# netbox-enterprise-7b8d9f6c4d-abc12      1/1     Running   0          5m
# netbox-enterprise-worker-5f7c8d9-xyz34  1/1     Running   0          5m
# postgres-primary-0                      1/1     Running   0          5m
# redis-master-0                          1/1     Running   0          5m

Verify Services

# Check all services are accessible
kubectl get svc -n netbox-enterprise

# Check service endpoints
kubectl get endpoints -n netbox-enterprise

Access NetBox Enterprise

Retrieve the admin password:

kubectl -n netbox-enterprise get secret netbox-enterprise-secret-config -o jsonpath='{.data.password}' | base64 -d

Access the application:

# Port forward to access NetBox
kubectl port-forward -n netbox-enterprise svc/netbox-enterprise 8080:80

# Access at http://localhost:8080
# Username: admin
# Password: (from command above)

Verify Database Connectivity

# Test database connection from NetBox pod
kubectl exec -n netbox-enterprise deployment/netbox-enterprise -- \
  python manage.py dbshell -c "SELECT version();"

Check Application Health

# Test health endpoint
kubectl exec -n netbox-enterprise deployment/netbox-enterprise -- \
  curl -f http://localhost:8080/health/

# Check Django system status
kubectl exec -n netbox-enterprise deployment/netbox-enterprise -- \
  python manage.py check --deploy

Additional Verification Steps

# Check initialization job
kubectl get jobs -n netbox-enterprise
kubectl logs -n netbox-enterprise job/netbox-enterprise-init

# Check application logs
kubectl logs -n netbox-enterprise deployment/netbox-enterprise --tail=50

# Check worker logs
kubectl logs -n netbox-enterprise deployment/netbox-enterprise-worker --tail=50

The initialization job runs database migrations and creates the superuser account automatically.

Accessing NetBox Enterprise

Using LoadBalancer Service

If your cluster supports LoadBalancer services:

# Get the external IP
kubectl get svc netbox-enterprise -n netbox-enterprise

# Access NetBox at http://EXTERNAL-IP

Using Ingress

If you configured Ingress:

# Verify Ingress is created
kubectl get ingress -n netbox-enterprise

# Access NetBox at your configured hostname (e.g., https://netbox.company.com)

Using Port Forwarding (for testing)

# Forward local port to NetBox service
kubectl port-forward -n netbox-enterprise svc/netbox-enterprise 8080:80

# Access NetBox at http://localhost:8080

Default Login

Use the credentials configured in your values file:

• Username: As configured in superuserUsername (default: admin)
• Password: Retrieved from the secret

To retrieve the admin password:

kubectl -n netbox-enterprise get secret netbox-enterprise-secret-config -o jsonpath='{.data.password}' | base64 -d

Platform-Specific Notes

AWS EKS

• Ensure your EKS cluster has the EBS CSI driver for persistent volumes
• Use AWS Load Balancer Controller for better LoadBalancer integration
• For RDS PostgreSQL, use the endpoint format: your-instance.region.rds.amazonaws.com
• For ElastiCache Redis, ensure security groups allow access from EKS nodes

Azure AKS

• Use Azure Disk CSI driver for persistent volumes
• Configure Azure Load Balancer annotations if needed
• For Azure Database for PostgreSQL, use the format: your-server.postgres.database.azure.com
• For Azure Cache for Redis, ensure firewall rules allow AKS subnet

Google GKE

• GKE includes CSI drivers by default
• Use GCP Load Balancer for service exposure
• For Cloud SQL, use the connection name format or private IP
• For Memorystore Redis, use the private IP address

Private Registry Deployments

For environments with restricted internet access, follow these steps:

Step 1: Mirror Images to Private Registry

Download the image mirroring script (optional):

curl -O https://netboxlabs.com/docs/files/private-registry.sh
chmod +x private-registry.sh

Manual Process (Complete Command List)

Set your private registry URL:

export MY_REGISTRY="mycompany.jfrog.io/nbe"

Pull all required images from NetBox Labs registries:

# Core NetBox Enterprise images
docker pull proxy.enterprise.netboxlabs.com/proxy/netbox-enterprise/ghcr.io/netboxlabs/nbe-core:4.2.9_main-191
docker pull proxy.enterprise.netboxlabs.com/proxy/netbox-enterprise/netboxlabs/nbe-utils:7

# Diode components
docker pull proxy.enterprise.netboxlabs.com/proxy/netbox-enterprise/docker.io/netboxlabs/diode-auth:1.2.0
docker pull proxy.enterprise.netboxlabs.com/anonymous/index.docker.io/netboxlabs/diode-ingester:1.2.0
docker pull proxy.enterprise.netboxlabs.com/anonymous/index.docker.io/netboxlabs/diode-reconciler:1.2.0
docker pull proxy.enterprise.netboxlabs.com/proxy/netbox-enterprise/ghcr.io/netboxlabs/diode-reconciler-pro:1.0.0

# Database and infrastructure
docker pull proxy.enterprise.netboxlabs.com/anonymous/index.docker.io/bitnami/redis:7.4.3-debian-12-r0
docker pull proxy.enterprise.netboxlabs.com/anonymous/registry.developers.crunchydata.com/crunchydata/postgres-operator:ubi9-5.8.2-0

# Security and utilities
docker pull proxy.enterprise.netboxlabs.com/anonymous/index.docker.io/oryd/hydra:v2.3.0
docker pull proxy.enterprise.netboxlabs.com/anonymous/index.docker.io/library/busybox:1.37
docker pull proxy.enterprise.netboxlabs.com/proxy/netbox-enterprise/busybox:latest

# Replicated SDK
docker pull proxy.enterprise.netboxlabs.com/proxy/netbox-enterprise/registry.replicated.com/library/replicated-sdk-image:1.7.0

# Ingress controller (if using internal)
docker pull proxy.enterprise.netboxlabs.com/anonymous/registry.k8s.io/ingress-nginx/controller:v1.12.1
docker pull proxy.enterprise.netboxlabs.com/anonymous/registry.k8s.io/ingress-nginx/kube-webhook-certgen:v1.5.2

Tag and push all images to your private registry:

# Core NetBox Enterprise images
docker tag proxy.enterprise.netboxlabs.com/proxy/netbox-enterprise/ghcr.io/netboxlabs/nbe-core:4.2.9_main-191 $MY_REGISTRY/netbox-enterprise/nbe-core:4.2.9_main-191
docker push $MY_REGISTRY/netbox-enterprise/nbe-core:4.2.9_main-191

docker tag proxy.enterprise.netboxlabs.com/proxy/netbox-enterprise/netboxlabs/nbe-utils:7 $MY_REGISTRY/netbox-enterprise/nbe-utils:7
docker push $MY_REGISTRY/netbox-enterprise/nbe-utils:7

# Diode components
docker tag proxy.enterprise.netboxlabs.com/proxy/netbox-enterprise/docker.io/netboxlabs/diode-auth:1.2.0 $MY_REGISTRY/netbox-enterprise/diode-auth:1.2.0
docker push $MY_REGISTRY/netbox-enterprise/diode-auth:1.2.0

docker tag proxy.enterprise.netboxlabs.com/anonymous/index.docker.io/netboxlabs/diode-ingester:1.2.0 $MY_REGISTRY/netbox-enterprise/diode-ingester:1.2.0
docker push $MY_REGISTRY/netbox-enterprise/diode-ingester:1.2.0

docker tag proxy.enterprise.netboxlabs.com/anonymous/index.docker.io/netboxlabs/diode-reconciler:1.2.0 $MY_REGISTRY/netbox-enterprise/diode-reconciler:1.2.0
docker push $MY_REGISTRY/netbox-enterprise/diode-reconciler:1.2.0

docker tag proxy.enterprise.netboxlabs.com/proxy/netbox-enterprise/ghcr.io/netboxlabs/diode-reconciler-pro:1.0.0 $MY_REGISTRY/netbox-enterprise/diode-reconciler-pro:1.0.0
docker push $MY_REGISTRY/netbox-enterprise/diode-reconciler-pro:1.0.0

# Database and infrastructure
docker tag proxy.enterprise.netboxlabs.com/anonymous/index.docker.io/bitnami/redis:7.4.3-debian-12-r0 $MY_REGISTRY/netbox-enterprise/redis:7.4.3-debian-12-r0
docker push $MY_REGISTRY/netbox-enterprise/redis:7.4.3-debian-12-r0

docker tag proxy.enterprise.netboxlabs.com/anonymous/registry.developers.crunchydata.com/crunchydata/postgres-operator:ubi9-5.8.2-0 $MY_REGISTRY/netbox-enterprise/postgres-operator:ubi9-5.8.2-0
docker push $MY_REGISTRY/netbox-enterprise/postgres-operator:ubi9-5.8.2-0

# Security and utilities
docker tag proxy.enterprise.netboxlabs.com/anonymous/index.docker.io/oryd/hydra:v2.3.0 $MY_REGISTRY/netbox-enterprise/hydra:v2.3.0
docker push $MY_REGISTRY/netbox-enterprise/hydra:v2.3.0

docker tag proxy.enterprise.netboxlabs.com/anonymous/index.docker.io/library/busybox:1.37 $MY_REGISTRY/netbox-enterprise/busybox:1.37
docker push $MY_REGISTRY/netbox-enterprise/busybox:1.37

docker tag proxy.enterprise.netboxlabs.com/proxy/netbox-enterprise/busybox:latest $MY_REGISTRY/netbox-enterprise/busybox:latest
docker push $MY_REGISTRY/netbox-enterprise/busybox:latest

# Replicated SDK
docker tag proxy.enterprise.netboxlabs.com/proxy/netbox-enterprise/registry.replicated.com/library/replicated-sdk-image:1.7.0 $MY_REGISTRY/netbox-enterprise/replicated-sdk-image:1.7.0
docker push $MY_REGISTRY/netbox-enterprise/replicated-sdk-image:1.7.0

# Ingress controller (if using internal)
docker tag proxy.enterprise.netboxlabs.com/anonymous/registry.k8s.io/ingress-nginx/controller:v1.12.1 $MY_REGISTRY/netbox-enterprise/ingress-nginx-controller:v1.12.1
docker push $MY_REGISTRY/netbox-enterprise/ingress-nginx-controller:v1.12.1

docker tag proxy.enterprise.netboxlabs.com/anonymous/registry.k8s.io/ingress-nginx/kube-webhook-certgen:v1.5.2 $MY_REGISTRY/netbox-enterprise/kube-webhook-certgen:v1.5.2
docker push $MY_REGISTRY/netbox-enterprise/kube-webhook-certgen:v1.5.2

Alternative: Using the Script

For automated processing, you can use the provided script:

# Use the script to automate the mirroring process
./private-registry.sh $MY_REGISTRY > image-mirror-commands.sh
chmod +x image-mirror-commands.sh
./image-mirror-commands.sh

Step 2: Generate Private Registry Configuration

Download the private registry template:

curl -O https://netboxlabs.com/docs/files/private-registry.yaml

Update the template with your registry URL:

# Manual method (recommended for production)
sed -e 's|MY_REGISTRY|mycompany.jfrog.io/nbe|g' private-registry.yaml > my-private-registry.yaml

Step 3: Install with Private Registry

# Download Helm charts for offline installation
helm pull oci://registry.netboxlabs.com/netbox-enterprise/beta/netbox-enterprise --version 1.11.4

# Install with private registry configuration
helm install netbox-enterprise ./netbox-enterprise-1.11.4.tgz \
  --values netbox-enterprise-values.yaml \
  --values values-extra.yaml \
  --values my-private-registry.yaml \
  --create-namespace \
  --namespace netbox-enterprise

Next Steps

After successful installation, continue with:

1. Operations - Backup, upgrade, and scaling procedures
2. Troubleshooting - Common issues and solutions

For the complete workflow:

1. Overview - Architecture overview
2. Prerequisites - System requirements
3. Installation (this guide) - Installation procedures and verification
4. Operations - Ongoing operations
5. Troubleshooting - Problem resolution