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:
- Operations - Backup, upgrade, and scaling procedures
- Troubleshooting - Common issues and solutions
For the complete workflow:
- Overview - Architecture overview
- Prerequisites - System requirements
- Installation (this guide) - Installation procedures and verification
- Operations - Ongoing operations
- Troubleshooting - Problem resolution