Upgrading

Installation Journey

Prerequisites → Install → Upgrading (you are here)

This guide covers how to upgrade NetBox Enterprise to a new chart version, including CRD updates and rollback procedures.

Pre-Upgrade Checklist

Before upgrading:

1. Review the release notes for the target version
2. Back up your database — see Backups if using Velero
3. Verify current state — ensure all components are healthy:

kubectl -n netbox get netboxenterprises
kubectl -n netbox get pods

4. Check for breaking changes in values.yaml between versions

Upgrade the Chart

1. Upgrade CRDs

Helm does not upgrade CRDs automatically. Upgrade all three CRD charts before the operator:

helm upgrade netbox-enterprise-crds \
  oci://registry.enterprise.netboxlabs.com/netbox-enterprise/stable-v2/netbox-enterprise-crds \
  --version 2.1.0 \
  --namespace netbox

helm upgrade netbox-enterprise-crds-pgo \
  oci://registry.enterprise.netboxlabs.com/netbox-enterprise/stable-v2/netbox-enterprise-crds-pgo \
  --version 2.1.0 \
  --namespace netbox

helm upgrade netbox-enterprise-crds-redis \
  oci://registry.enterprise.netboxlabs.com/netbox-enterprise/stable-v2/netbox-enterprise-crds-redis \
  --version 2.1.0 \
  --namespace netbox

warning

Always upgrade CRDs before running helm upgrade on the operator. CRDs define the schema for the NetBoxEnterprise resource — upgrading the operator without updating CRDs can cause validation errors.

2. Upgrade the Operator

helm upgrade netbox-enterprise \
  oci://registry.enterprise.netboxlabs.com/netbox-enterprise/stable-v2/netbox-enterprise \
  --version 2.1.0 \
  --namespace netbox \
  --values netbox-values.yaml

Monitor the Upgrade

Watch the operator reconcile with the new version:

kubectl -n netbox get pods -w

Check the operator logs for reconciliation progress:

kubectl -n netbox logs -l app.kubernetes.io/name=nbe-operator -f --tail=50

Verify the upgrade completed:

kubectl -n netbox get netboxenterprises -o wide

The VERSION column should reflect the new operator version.

Check Release Status

helm status netbox-enterprise --namespace netbox

helm history netbox-enterprise --namespace netbox

Rollback

If the upgrade causes issues, roll back to the previous release:

helm rollback netbox-enterprise --namespace netbox

To roll back to a specific revision:

helm history netbox-enterprise --namespace netbox
helm rollback netbox-enterprise <revision-number> --namespace netbox

note

Rolling back the Helm release reverts the operator deployment and values, but does not automatically downgrade CRDs. CRD changes are typically additive (new fields) and backward-compatible, so this is usually safe.

Suspend Reconciliation

If you need to pause the operator during troubleshooting without rolling back:

helm upgrade netbox-enterprise \
  oci://registry.enterprise.netboxlabs.com/netbox-enterprise/stable-v2/netbox-enterprise \
  --version 2.1.0 \
  --namespace netbox \
  --reuse-values \
  --set netboxEnterprise.spec.suspend=true

The operator will stop reconciling the NetBoxEnterprise until suspend is set back to false. Existing workloads continue running.

Next Steps

• Troubleshooting — Diagnose upgrade issues
• Maintenance Mode — Take NetBox offline for major changes