Upgrades

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. It prompts you before each component and any component can be skipped by answering "n" at the prompt.

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 in non-interactive mode:

nf-upgrade -y

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.