Skip to main content
Enterprise

Upgrading

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
  1. Check for breaking changes in values.yaml between versions

Upgrade the Chart​

Standard Upgrade​

helm upgrade netbox-enterprise \
  oci://registry.enterprise.netboxlabs.com/library/nbe-operator \
  --namespace netbox \
  --values netbox-values.yaml

Upgrade CRDs​

Helm does not upgrade CRDs automatically. Before upgrading the chart, apply the latest CRDs either by upgrading the CRD chart or applying directly:

# Option 1: Upgrade the CRD chart
helm upgrade nbe-crds \
  oci://registry.enterprise.netboxlabs.com/library/nbe-operator-crds \
  --namespace netbox
# Option 2: Apply the CRD YAML directly
kubectl apply -f https://netboxlabs.com/docs/files/helm/netboxenterprises.netboxlabs.com-v2.0.0.yaml
warning

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

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/library/nbe-operator \
  --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​