NetBox Enterprise Helm Values Configuration Guide

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.

This guide covers the configuration and customization of NetBox Enterprise Helm deployments using overlay values files.

Overview

The NetBox Enterprise Helm chart supports a two-tier configuration approach:

Base values file: Generated from the Enterprise Portal containing license information and default configurations
Overlay values file: Custom values file (values-extra.yaml) containing environment-specific customizations

This approach ensures license information remains intact while allowing environment-specific customizations.

Quick Start

Authentication Setup

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

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

# Authenticate with registries
docker login proxy.enterprise.netboxlabs.com -u $USERNAME -p $LICENSE_ID
helm registry login registry.enterprise.netboxlabs.com -u $USERNAME -p $LICENSE_ID

Basic Workflow

# Helm authentication (to netboxlabs.com)
helm registry login registry.enterprise.netboxlabs.com -u $USERNAME -p $LICENSE_ID

# 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

# Deploy with your customizations
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

Quick Configuration Reference

Essential Commands

# Generate base values file
helm show values oci://registry.enterprise.netboxlabs.com/netbox-enterprise/beta/netbox-enterprise \
  --version 1.11.4 > netbox-enterprise-values.yaml

# Install with Enterprise Portal values + custom overlay
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

Configuration Commands

# Show default values from chart
helm show values oci://registry.enterprise.netboxlabs.com/netbox-enterprise/beta/netbox-enterprise \
  ${CHART_VERSION:+--version $CHART_VERSION}

# Validate your values file
helm template 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} \
  --dry-run

# Test configuration without installing
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} \
  --dry-run --debug

# Get current values from installed release
helm get values netbox-enterprise -n netbox-enterprise

# Compare values between releases
helm get values netbox-enterprise -n netbox-enterprise --revision 1
helm get values netbox-enterprise -n netbox-enterprise --revision 2

Common Configuration Patterns

Basic Ingress with TLS

netbox:
  ingress:
    enabled: true
    hosts:
      - host: netbox.company.com
        paths: [{ path: '/', pathType: 'Prefix' }]
    tls:
      - secretName: netbox-tls
        hosts: ['netbox.company.com']
    annotations:
      cert-manager.io/cluster-issuer: 'letsencrypt-prod'

See also: Prerequisites - Network Requirements for DNS and certificate setup

Production Resources

netbox:
  replicaCount: 3
  resources:
    requests: { cpu: '1000m', memory: '4Gi' }
    limits: { cpu: '4000m', memory: '8Gi' }
  worker:
    replicaCount: 3
    resources:
      requests: { cpu: '500m', memory: '1Gi' }
      limits: { cpu: '2000m', memory: '4Gi' }

Production Resources

For production deployments, configure appropriate resource allocation:

netbox:
  replicaCount: 3
  resources:
    requests: { cpu: '1000m', memory: '4Gi' }
    limits: { cpu: '4000m', memory: '8Gi' }
  worker:
    replicaCount: 3
    resources:
      requests: { cpu: '500m', memory: '1Gi' }
      limits: { cpu: '2000m', memory: '4Gi' }

Resource Recommendations

Development: 1 CPU, 2Gi memory
Staging: 2 CPU, 4Gi memory
Production: 4+ CPU, 8Gi+ memory

Scaling Considerations

Scale web pods for user load
Scale worker pods for background tasks
Monitor resource usage and adjust accordingly

External Database (Secrets Method)

# First create secrets:
# kubectl create secret generic nbe-external-database-secret-netbox --from-literal=uri='postgres://user:pass@host:5432/netbox'

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

External Database Configuration

For production deployments, use external PostgreSQL with secrets:

# First create secrets:
# kubectl create secret generic nbe-external-database-secret-netbox --from-literal=uri='postgres://user:pass@host:5432/netbox'

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

Creating Database Secrets

# Create database secrets for NetBox, Diode, and Hydra
kubectl create secret generic nbe-external-database-secret-netbox --from-literal=uri='postgres://user:password@host:port/netbox_db'
kubectl create secret generic nbe-external-database-secret-diode --from-literal=uri='postgres://user:password@host:port/diode_db'
kubectl create secret generic nbe-external-database-secret-hydra --from-literal=uri='postgres://user:password@host:port/hydra_db'

Database Requirements

PostgreSQL 13+
Dedicated databases for NetBox, Diode, and Hydra
Proper user permissions and connection limits

Private Registry

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

See also: Prerequisites - Private Registry Setup for complete setup | Troubleshooting - Registry Authentication for auth problems

Custom Storage

netbox:
  persistence:
    enabled: true
    storageClass: 'fast-ssd'
    size: '100Gi'

See also: Prerequisites - Storage Requirements for storage class setup

Prerequisites

This guide assumes you have completed the system prerequisites and have:

NetBox Enterprise license with Enterprise Portal access
Kubernetes cluster (1.26+) with kubectl configured
Helm 3.17.3 or higher

Configuration Workflow

Step 1: Generate Base Values File

Access the Enterprise Portal and generate your base values file:

# Set authentication variables
export NETBOX_USERNAME="your-email@company.com"
export SERVICE_ACCOUNT_TOKEN="your-service-account-token"

# Helm authentication (to netboxlabs.com)
helm registry login registry.enterprise.netboxlabs.com -u $USERNAME -p $SERVICE_ACCOUNT_TOKEN

# Get default values
helm show values oci://registry.enterprise.netboxlabs.com/netbox-enterprise/beta/netbox-enterprise \
  --version 1.11.4 > netbox-enterprise-values.yaml

Step 2: Create Overlay Values File

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

# values-extra.yaml
netbox:
  ingress:
    hosts:
      - host: netbox.example.com
  superuserEmail: 'admin@example.com'
  extraEnvironment:
    TZ: 'UTC'

Step 3: Deploy with Multiple Values Files

Deploy the chart using both the base and overlay values files:

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

Common Configuration Patterns

Ingress Configuration

Configure external access to NetBox Enterprise:

netbox:
  ingress:
    enabled: true
    className: 'nginx'
    hosts:
      - host: netbox.example.com
        paths:
          - path: /
            pathType: Prefix
    tls:
      - secretName: netbox-tls
        hosts:
          - netbox.example.com
    annotations:
      cert-manager.io/cluster-issuer: 'letsencrypt-prod'
      nginx.ingress.kubernetes.io/proxy-body-size: '100m'

Resource Allocation

Configure resource requests and limits for production deployments:

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

  replicaCount: 3

  worker:
    replicaCount: 3
    resources:
      requests:
        cpu: '500m'
        memory: '1Gi'
      limits:
        cpu: '2000m'
        memory: '4Gi'

External Database Configuration

Configure external PostgreSQL using secrets (recommended approach):

# Create database secrets for NetBox, Diode, and Hydra
kubectl create secret generic nbe-external-database-secret-netbox --from-literal=uri='postgres://user:password@host:port/netbox_db'
kubectl create secret generic nbe-external-database-secret-diode --from-literal=uri='postgres://user:password@host:port/diode_db'
kubectl create secret generic nbe-external-database-secret-hydra --from-literal=uri='postgres://user:password@host:port/hydra_db'

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

# Install with external database configuration
helm install netbox-enterprise \
  oci://registry.enterprise.netboxlabs.com/netbox-enterprise/beta/netbox-enterprise \
  --values netbox-enterprise-values.yaml \
  --values external-database-values.yaml

Note: If your password contains special characters, URL-encode it first:

printf '%s' 'my@password!' | jq -sRr '@uri'

Alternative environment variable approach (legacy):

netbox:
  extraEnvironment:
    DATABASE_URL: 'postgresql://netbox:password@postgres.example.com:5432/netbox'
    REDIS_URL: 'redis://:password@redis.example.com:6379/0'
    CACHE_URL: 'redis://:password@redis.example.com:6379/1'

  postgresql:
    enabled: false

  redis:
    enabled: false

Private Registry Configuration

Configure private container registries for restrictive environments:

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

netbox:
  image:
    repository: 'registry.example.com/netbox/netbox-enterprise'
    tag: 'v1.11.4'

Advanced Configuration

Persistent Storage

Configure persistent storage for file uploads and media:

netbox:
  persistence:
    enabled: true
    storageClass: 'fast-ssd'
    size: '100Gi'
    accessMode: 'ReadWriteOnce'

Security Configuration

Configure security contexts and policies:

netbox:
  securityContext:
    runAsNonRoot: true
    runAsUser: 1000
    fsGroup: 1000

  podSecurityContext:
    seccompProfile:
      type: RuntimeDefault

Monitoring and Observability

Configure monitoring and metrics collection:

netbox:
  metrics:
    enabled: true
    serviceMonitor:
      enabled: true
      namespace: 'monitoring'

  extraEnvironment:
    METRICS_ENABLED: 'true'
    LOGGING_LEVEL: 'INFO'

Validation and Testing

Configuration Validation

Validate configuration before deployment:

# Validate YAML syntax
helm template 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 \
  --dry-run

Testing Configuration

Test configuration without installing:

# Dry run installation
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 \
  --dry-run --debug

Post-Installation Verification

Verify configuration after installation:

# Check deployment status
kubectl get pods -n netbox-enterprise

# Check services
kubectl get svc -n netbox-enterprise

# Check ingress
kubectl get ingress -n netbox-enterprise

Common Configuration Issues

Database Connection Failures

# Test database connectivity
kubectl run -it --rm debug --image=postgres:14 --restart=Never -- \
  psql postgresql://user:pass@host:5432/dbname

Resource Constraints

# Check resource usage
kubectl describe pod -n netbox-enterprise <pod-name>
kubectl top nodes

Ingress Configuration Problems

# Verify ingress controller
kubectl get pods -A | grep ingress

# Check ingress events
kubectl describe ingress -n netbox-enterprise

Configuration Reference

Chart Values Structure

The chart follows a hierarchical structure:

global:
  # Global configuration options
  imageRegistry: ''
  imagePullSecrets: []

netbox:
  # NetBox-specific configuration
  image:
    repository: ''
    tag: ''

  ingress:
    enabled: false
    hosts: []

  resources:
    requests: {}
    limits: {}

postgresql:
  # PostgreSQL configuration
  enabled: true

redis:
  # Redis configuration
  enabled: true

diode:
  # Diode configuration
  enabled: true

Chart Information

Chart Repository: oci://registry.enterprise.netboxlabs.com/netbox-enterprise/beta/netbox-enterprise
Current Version: 1.11.4
Registry: registry.enterprise.netboxlabs.com

Documentation Links

Support

For technical support, contact NetBox Labs support with your deployment configuration (excluding sensitive information such as license keys and passwords).

Complete Installation Guide

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

For performance issues, see Troubleshooting - Performance Issues.

Overview​

Quick Start​

Authentication Setup​

Basic Workflow​

Quick Configuration Reference​

Essential Commands​

Configuration Commands​

Common Configuration Patterns​

Production Resources​

Resource Recommendations​

Scaling Considerations​

External Database Configuration​

Creating Database Secrets​

Database Requirements​

Prerequisites​

Configuration Workflow​

Step 1: Generate Base Values File​

Step 2: Create Overlay Values File​

Step 3: Deploy with Multiple Values Files​

Common Configuration Patterns​

Ingress Configuration​

Resource Allocation​

External Database Configuration​

Private Registry Configuration​

Advanced Configuration​

Persistent Storage​

Security Configuration​

Monitoring and Observability​

Validation and Testing​

Configuration Validation​

Testing Configuration​

Post-Installation Verification​

Common Configuration Issues​

Configuration Reference​

Chart Values Structure​

Chart Information​

Documentation Links​

Support​

Complete Installation Guide​

Overview

Quick Start

Authentication Setup

Basic Workflow

Quick Configuration Reference

Essential Commands

Configuration Commands

Common Configuration Patterns

Production Resources

Resource Recommendations

Scaling Considerations

External Database Configuration

Creating Database Secrets

Database Requirements

Prerequisites

Configuration Workflow

Step 1: Generate Base Values File

Step 2: Create Overlay Values File

Step 3: Deploy with Multiple Values Files

Common Configuration Patterns

Ingress Configuration

Resource Allocation

External Database Configuration

Private Registry Configuration

Advanced Configuration

Persistent Storage

Security Configuration

Monitoring and Observability

Validation and Testing

Configuration Validation

Testing Configuration

Post-Installation Verification

Common Configuration Issues

Configuration Reference

Chart Values Structure

Chart Information

Documentation Links

Support

Complete Installation Guide