Installation

Beta Notice: These Helm charts are currently in beta. While stable for testing and development environments, please thoroughly test in your specific environment before production deployment. For the most up-to-date information, please refer to the main documentation.

Quick Start - Get running fast
Authentication & Registry Setup - Required first steps
Standard Installation - Most common deployment
Configuration Options - Customization
Advanced Scenarios - Complex deployments
- External Database Configuration
- Private Registry Installation
Installation Verification - Confirm success
Platform-Specific Notes - Cloud provider details
Next Steps - What to do after installation

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

Installation Methods

Choose the installation method that best fits your environment:

Quick Start - Fastest path to deployment with defaults
Standard Installation - Production-ready with custom configuration
Private Registry Installation - For restrictive environments

Need help with configuration? See Values Guide for detailed configuration examples and patterns.

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.enterprise.netboxlabs.com/netbox-enterprise/beta/netbox-enterprise \
  --namespace netbox-enterprise \
  --create-namespace \
  --values netbox-enterprise-values.yaml \
  ${CHART_VERSION:+--version $CHART_VERSION}

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

⚠️ Important: Before starting, ensure you meet all prerequisites.

Verify deployment:

kubectl get pods -n netbox-enterprise
kubectl get ingress -n netbox-enterprise

Installation problems? See Troubleshooting - Installation Issues for common deployment problems.

Authentication & 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 Authentication Variables

# Set your credentials
export USERNAME="your-email@company.com"
export LICENSE_ID="your-license-id-here"

# Optional: Set specific Helm chart version (leave empty for latest)
export CHART_VERSION="1.11.4"  # or export CHART_VERSION="" for latest

# Verify they are set
echo "Username: $USERNAME"
echo "License ID: $LICENSE_ID"
echo "Chart Version: $CHART_VERSION"

Step 2: Log in to the Registries

# Log in to the Docker registry (for image pulls)
docker login proxy.enterprise.netboxlabs.com -u $USERNAME -p $LICENSE_ID

# Log in to the OCI registry for Helm charts
helm registry login registry.enterprise.netboxlabs.com -u $USERNAME -p $LICENSE_ID

Note: Docker images are pulled from proxy.enterprise.netboxlabs.com but authentication uses your LICENSE_ID

Step 3: Pull the Values File

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

# Get default values
helm show values oci://registry.enterprise.netboxlabs.com/netbox-enterprise/beta/netbox-enterprise \
  ${CHART_VERSION:+--version $CHART_VERSION} > 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.

Standard Installation

This is the recommended approach for production deployments with custom configuration.

Step 1: Complete Authentication Setup

Follow the Authentication & Registry Setup steps above.

Step 2: Download Configuration Template

Download the configuration template for customization:

curl -O https://netboxlabs.com/docs/files/values-extra.yaml
vim values-extra.yaml

Step 3: Configure Your Values

Create a values-extra.yaml file with your customizations:

# Example production configuration
netbox:
  ingress:
    enabled: true
    hosts:
      - host: netbox.company.com
        paths: [{ path: '/', pathType: 'Prefix' }]

For complete configuration examples, see Values Guide - Quick Configuration Reference.

Step 4: Install NetBox Enterprise

helm install netbox-enterprise \
  oci://registry.enterprise.netboxlabs.com/netbox-enterprise/beta/netbox-enterprise \
  --values netbox-enterprise-values.yaml \
  --values values-extra.yaml \
  ${CHART_VERSION:+--version $CHART_VERSION} \
  --create-namespace \
  --namespace netbox-enterprise

Installation failing? Check Troubleshooting - Installation Issues for common problems and solutions.

Installation Options

--wait: Wait until deployment is ready
--timeout 10m: Set timeout for installation
--dry-run: Preview without installing
--debug: Show debug information

Configuration Options

Basic 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

Resource Configuration

For production deployments, configure appropriate resources:

netbox:
  resources:
    requests:
      cpu: '1000m'
      memory: '4Gi'
    limits:
      cpu: '4000m'
      memory: '8Gi'

Advanced Scenarios

External Database Configuration

For production environments, you may want to use an external PostgreSQL database:

# External database configuration
netbox:
  externalDatabase:
    enabled: true
    secretName: 'nbe-external-database-secret-netbox'
  postgresql:
    enabled: false

Preflight Checks

Before installation, you can run preflight checks:

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

Standard Installation with Custom Values

# Standard installation with custom values
helm install netbox-enterprise \
  oci://registry.enterprise.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 Verification

After installation, verify the deployment:

Check Pod Status

# Check all pods are running
kubectl get pods -n netbox-enterprise

# Check specific deployments
kubectl get deployment -n netbox-enterprise
kubectl get statefulset -n netbox-enterprise

Check Services and Ingress

# Check services
kubectl get svc -n netbox-enterprise

# Check ingress
kubectl get ingress -n netbox-enterprise

# Check 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

# Then visit http://your-netbox-instance:8080

Platform-Specific Notes

AWS EKS

For AWS EKS deployments:

# EKS-specific configuration
netbox:
  service:
    type: LoadBalancer
    annotations:
      service.beta.kubernetes.io/aws-load-balancer-type: 'nlb'

Azure AKS

For Azure AKS deployments:

# AKS-specific configuration
netbox:
  service:
    type: LoadBalancer
    annotations:
      service.beta.kubernetes.io/azure-load-balancer-internal: 'true'

Google GKE

For Google GKE deployments:

# GKE-specific configuration
netbox:
  service:
    type: LoadBalancer
    annotations:
      cloud.google.com/load-balancer-type: 'Internal'

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

Private Registry Installation

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/ghcr.io/netboxlabs/nbe-worker:4.2.9_main-191

# Additional required images would be listed here...

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

# Additional tagging and pushing commands would be listed here...

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: Configure Private Registry Values

global:
  imageRegistry: 'registry.company.com/netbox'
  imagePullSecrets:
    - name: 'registry-credentials'

For complete private registry setup, see Prerequisites - Private Registry Requirements.

Step 3: Install with Private Registry

# Download Helm charts for offline installation
# Option 1: Set version variable (leave empty for latest)
export CHART_VERSION="1.11.4"  # or export CHART_VERSION="" for latest

helm pull oci://registry.enterprise.netboxlabs.com/netbox-enterprise/beta/netbox-enterprise ${CHART_VERSION:+--version $CHART_VERSION}

# Install with private registry configuration
helm install netbox-enterprise ./netbox-enterprise-${CHART_VERSION:-latest}.tgz \
  --values netbox-enterprise-values.yaml \
  --values values-extra.yaml \
  --values my-private-registry.yaml \
  --create-namespace \
  --namespace netbox-enterprise

Conditional Version Usage Explained

The ${CHART_VERSION:+--version $CHART_VERSION} syntax works as follows:

# When CHART_VERSION is set and non-empty:
export CHART_VERSION="1.11.4"
# Expands to: helm pull oci://registry... --version 1.11.4

# When CHART_VERSION is empty or unset:
export CHART_VERSION=""
# Expands to: helm pull oci://registry... (no --version flag)

Alternative approaches:

# Using a function
pull_chart() {
    local version="$1"
    if [[ -n "$version" ]]; then
        helm pull oci://registry.enterprise.netboxlabs.com/netbox-enterprise/beta/netbox-enterprise --version "$version"
    else
        helm pull oci://registry.enterprise.netboxlabs.com/netbox-enterprise/beta/netbox-enterprise
    fi
}

# Usage: pull_chart "1.11.4" or pull_chart ""

# Using conditional command construction
VERSION_ARG=""
if [[ -n "$CHART_VERSION" ]]; then
    VERSION_ARG="--version $CHART_VERSION"
fi
helm pull oci://registry.enterprise.netboxlabs.com/netbox-enterprise/beta/netbox-enterprise $VERSION_ARG

Next Steps

After successful installation, continue with:

Values Guide - Configuration reference
Operations - Backup, upgrade, and scaling procedures
Troubleshooting - Common issues and solutions

Complete Installation Guide

Overview - Architecture and approach
Prerequisites - System requirements
→ Installation - Installation procedures
Values Guide - Configuration reference
Operations - Backup and maintenance
Troubleshooting - Problem resolution

Table of Contents​

Installation Methods​

Quick Start​

Authentication & Registry Setup​

Step 1: Set Authentication Variables​

Step 2: Log in to the Registries​

Step 3: Pull the Values File​

Standard Installation​

Step 1: Complete Authentication Setup​

Step 2: Download Configuration Template​

Step 3: Configure Your Values​

Step 4: Install NetBox Enterprise​

Installation Options​

Configuration Options​

Basic Ingress Configuration​

Resource Configuration​

Advanced Scenarios​

External Database Configuration​

Preflight Checks​

Standard Installation with Custom Values​

Installation Verification​

Check Pod Status​

Check Services and Ingress​

Access NetBox Enterprise​

Platform-Specific Notes​

AWS EKS​

Azure AKS​

Google GKE​

Default Login​

Private Registry Installation​

Step 1: Mirror Images to Private Registry​

Manual Process (Complete Command List)​

Alternative: Using the Script​

Step 2: Configure Private Registry Values​

Step 3: Install with Private Registry​

Conditional Version Usage Explained​

Next Steps​

Complete Installation Guide​

Table of Contents