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

The controller and all edge routers must always run the same OpenZiti version. Always upgrade the routers first, then the controller. Running mismatched versions can cause connectivity issues.

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 --router --controller

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

Command reference

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

Flag	Description
-y	Non-interactive mode — accept all prompts
-S, --skip-snapshot	Skip the automatic pre-upgrade database snapshot
--router	Upgrade the edge router
--controller	Upgrade the controller
--ziti-host	Upgrade the ziti-host tunneler
--support	Upgrade the support stack
--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 --router --controller    # Upgrade router and controller only
nf-upgrade --controller --skip-snapshot  # Upgrade controller, skip the snapshot

tip

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

What the upgrade does

The upgrade script walks through four components in order:

1. 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.

2. Controller

• Displays the currently running controller version.
• Takes an automatic snapshot of the BoltDB database (via nf-create-snapshot).
• 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.

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

• Upgrades the NetFoundry support Helm chart, which includes Elasticsearch, RabbitMQ, Logstash, and Kibana.

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	2.0.5
HELM_CHART_VERSION_ROUTER	ziti-router chart version	1.5.1
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 ./On-Prem-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 are not included in the tarball.

3. Run the upgrade

nf-upgrade

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

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

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 and all edge routers must run the same OpenZiti version. The upgrade script handles this by upgrading the routers first, then the controller.

tip

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

Backup and recovery

Automatic snapshots

The upgrade script automatically runs nf-create-snapshot before upgrading the controller. This creates a timestamped copy of the BoltDB database file that can be used to restore the controller to its pre-upgrade state.

Manual snapshots

You can take a snapshot 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 will not 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 are 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 is not 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 are 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 does not affect the upgrade itself.