Upgrade your installation

NetFoundry Self-Hosted provides a guided, interactive upgrade script that walks through upgrading each component one at a time. Each component can be individually skipped, so you can upgrade only what you need.

Before you upgrade

warning

Always upgrade the controller before the routers. Routers running versions below 1.7 will fail to connect after a controller upgrade. The upgrade script warns you if incompatible routers are detected before proceeding.

Before starting an upgrade:

1. Check cluster health: Run nf-status and verify all pods are running and healthy.
2. Review the changelog: Check the release notes for breaking changes or required manual steps.
3. Consider backups: The upgrade script automatically takes a local database snapshot before upgrading the controller, but for disaster recovery you should also have Velero/S3 backups configured.
4. Update the package: Install the new version of netfoundry-self-hosted before running the upgrade. The package includes an updated .env file with tested, compatible Helm chart versions.

Run the upgrade

nf-upgrade

The script is fully interactive by default. It prompts you before each component and any component can be skipped by answering "n" at the prompt.

To upgrade specific components without prompts, use the component flags:

nf-upgrade --controller --router

When component flags are provided, only the specified components are upgraded and all prompts are automatically accepted.

Command reference

nf-upgrade [-y] [-S] [--controller] [--router] [--ziti-host] [--support] [--console] [--zlan] [--k3s] [--skip-snapshot]

Flag	Description
-y	Non-interactive mode—accept all prompts
-S, --skip-snapshot	Skip the automatic pre-upgrade database snapshot
--controller	Upgrade the controller
--router	Upgrade the edge router
--ziti-host	Upgrade the ziti-host tunneler
--support	Upgrade the support stack
--console	Upgrade (or install) Ziti Console Enterprise
--zlan	Upgrade the zLAN Console
--k3s	Upgrade K3s

Examples:

nf-upgrade                               # Interactive—prompt for each component
nf-upgrade -y                            # Upgrade all components, no prompts
nf-upgrade --controller                  # Upgrade only the controller
nf-upgrade --controller --router         # Upgrade controller and router only
nf-upgrade --controller --skip-snapshot  # Upgrade controller, skip the snapshot
nf-upgrade --console                     # Upgrade or install Ziti Console Enterprise

tip

Run nf-status before and after the upgrade to confirm everything is healthy.

What the upgrade does

The upgrade script walks through components in this order:

1. Controller

• Displays the currently running controller version.
• Takes an automatic snapshot of the BoltDB database (via nf-create-snapshot).
• Detects major Helm chart version crossings and runs the appropriate upgrade hook automatically (for example, the v2→v3 hook handles PKI consolidation and cluster.mode injection).
• Runs helm upgrade for the ziti-controller chart.
• Displays the new controller version after the upgrade completes.

note

The automatic pre-upgrade snapshot gives you a restore point if something goes wrong. You can also take manual snapshots at any time with nf-create-snapshot.

2. Edge router

• Displays the currently running router version.
• Runs helm upgrade for the ziti-router-1 chart.
• Displays the new router version after the upgrade completes.

3. ziti-host

• Only offered if a helm-managed ziti-host deployment exists in the support namespace.
• Displays the current version and runs helm upgrade for the ziti-host chart.

4. Support stack

• Detects major support chart version crossings and runs the appropriate upgrade hook automatically (for example, the v0→v1 hook deploys ZMP and Redis, migrates Grafana datasources, and consolidates RabbitMQ queues).
• Upgrades the NetFoundry support Helm chart.

5. Ziti Console Enterprise

• Only offered if --console is passed or in interactive mode.
• If Ziti Console Enterprise is already installed, upgrades it in place.
• If it's not installed, offers to install it. Requires NetFoundry container registry credentials (REGISTRY_USERNAME and REGISTRY_PASSWORD).

6. zLAN Console

• Only offered if the zlan-console Helm release is already installed.
• Runs helm upgrade for the zlan-console chart.

Version management

Helm chart versions are pinned in the .env file at the root of the installation directory:

Variable	Controls	Example
HELM_CHART_VERSION_CTRL	ziti-controller chart version	3.2.0-pre6
HELM_CHART_VERSION_ROUTER	ziti-router chart version	3.0.0-pre5
HELM_CHART_VERSION_ZITI_HOST	ziti-host chart version	^1.1.0
HELM_CHART_VERSION_CERT_MANAGER	cert-manager chart version	^1.0.0
HELM_CHART_VERSION_TRUST_MANAGER	trust-manager chart version	^0.18.0

The OpenZiti application version (the version of OpenZiti software running inside the containers) is determined by the helm chart's appVersion. By default, upgrading a Helm chart also upgrades the OpenZiti application to the version bundled with that chart. This is the recommended approach, as each chart version is tested against a specific OpenZiti version.

If you need to pin or override the OpenZiti application version independently of the chart, set the image.tag field in your values file. For example, in controller-values.yml:

image:
  tag: "1.6.12"

Or in router-values.yml:

image:
  tag: "1.6.12"

When image.tag is set, Helm will use that specific container image tag instead of the chart's default appVersion. To return to the chart default, remove the image.tag override or set it to an empty string.

When you install a new version of the netfoundry-self-hosted package, the .env file is updated with tested, compatible chart versions. This is the primary mechanism for ensuring version compatibility across components.

Offline / air-gapped upgrades

For environments without internet access, upgrades use the same offline tarball approach as the initial installation. The new tarball contains updated Helm charts, container images, and scripts.

1. Transfer the new tarball

On a machine with internet access, download the new version of the offline tarball using your JFROG credentials and transfer it to the air-gapped host.

2. Extract over the existing installation

tar -zxf ./netfoundry-self-hosted-offline-<version>.tar.gz -C /opt/netfoundry/self-hosted

This overwrites scripts, Helm charts, and bundled images with the new versions. User-generated files (controller-values.yml, router-values.yml, .checkpoints/, etc.) are preserved since they aren't included in the tarball.

3. Run the upgrade

nf-upgrade

Or non-interactively, for all components or specific ones:

nf-upgrade -y
nf-upgrade --controller --router

Offline mode is auto-detected from the presence of packages/offline-helm-charts/—no manual export OFFLINE_MODE=true is needed. The upgrade script automatically imports the bundled container images into K3s and resolves Helm charts from the local directory instead of fetching from a remote repository.

warning

As with online upgrades, the controller must be upgraded before the routers. The upgrade script enforces this order automatically.

tip

Run nf-status before and after the upgrade to verify cluster health.

Backup and recovery

The upgrade script automatically takes a BoltDB snapshot before upgrading the controller. You can also take one manually at any time:

nf-create-snapshot

Restore from snapshot

To restore the controller database from a snapshot:

nf-restore-snapshot

The restore script will:

1. List available snapshots and let you choose one.
2. Temporarily stop the controller (this disrupts network services).
3. Replace the database file with the selected snapshot.
4. Restart the controller.

Velero backups

For full cluster backup and disaster recovery, configure automated Velero backups to S3. See the backups documentation for setup instructions.

Rollback

Some upgrades—particularly major Helm chart version changes—involve one-way operations such as PKI restructuring or database migrations. A standard helm rollback won't undo these changes. Instead, use the following approach.

Step 1: Roll back the application version

Pin the previous OpenZiti version by setting image.tag in your values file. For example, in controller-values.yml:

image:
  tag: "1.6.8"

Then re-apply the Helm chart:

helm upgrade --install ziti-controller openziti/ziti-controller \
  -n ziti --values ./controller-values.yml \
  --values ./helm-value-files/templates/support-stack-additions.yml \
  --wait --timeout 180s

note

Only include the support-stack-additions.yml values file if the support stack is installed. If you're unsure, check for .checkpoints/support.installed.

Run nf-status to verify the pods are running with the expected version.

Step 2: Restore from snapshot (if needed)

If rolling back the image tag isn't sufficient—for example, if a database migration in the new version is incompatible with the older binary—restore the pre-upgrade database snapshot:

nf-restore-snapshot

This will:

1. List available snapshots (the most recent one is the automatic pre-upgrade snapshot).
2. Stop the controller, replace the database with the selected snapshot, and restart it.

warning

Restoring a snapshot reverts all controller state (identities, policies, services, etc.) to the point when the snapshot was taken. Any changes made after the snapshot will be lost.

Skipping the pre-upgrade snapshot

If you're making multiple upgrade attempts in a row and don't need a new snapshot each time, pass -S or --skip-snapshot to skip the automatic snapshot:

nf-upgrade --controller --skip-snapshot

This only skips the automatic pre-upgrade snapshot. It doesn't affect the upgrade itself.