Upgrade Gateways

Firezone Gateways are designed to be easily upgraded with little or no planned downtime for your organization. This guide will walk you through the steps to upgrade your Gateway for both Docker and systemd deployments.

Version compatibility

Gateways are guaranteed to be compatible with Clients of the current and previous minor version. For example, Gateway version 1.4.X is compatible with all Client versions 1.3.X and 1.4.X but not with Clients from the 1.2.X version.

To ensure smooth access to all your Resources, we recommend updating your Clients and Gateways at least every 3 months. These updates do not have to happen in lock-step as the Firezone control plane automatically selects a compatible Gateway for each Client according to the compatibility described above.

To support Clients across multiple minor versions, you can deploy Gateways of different versions in the same site. For example, running Gateway 1.3.X, 1.4.X and 1.5.X within the same site will allow Clients from 1.2.X to 1.5.X to connect.

In order to safely upgrade your Gateways to a new version, you'll want to ensure that all of your Clients have upgraded at least to the prior minor version. For example, if you upgrade your Gateways to 1.5.X, all users should at least be using Client 1.4.0 of their respective platform.

Upgrade process

Upgrading a Gateway generally consists of simply replacing the binary or Docker image with the newer version and then restarting. See below for specific steps depending on how you've deployed your Gateway:

curl -fsSL \
  https://raw.githubusercontent.com/firezone/firezone/main/scripts/gateway-docker-upgrade.sh \
  | bash

# Stop the Gateway service. WARNING: This will cause brief downtime for this Gateway.
sudo systemctl stop firezone-gateway

# Move the old binary to a backup location
sudo mv /opt/firezone/bin/firezone-gateway /opt/firezone/bin/firezone-gateway.bak

# Start the Gateway service to trigger the upgrade
sudo systemctl start firezone-gateway

# Restore the old binary and restart the service

sudo systemctl stop firezone-gateway
sudo mv /usr/local/bin/firezone-gateway.bak /usr/local/bin/firezone-gateway
sudo systemctl start firezone-gateway

Verification

After running the upgrade, check that the version reported by the Gateway in the admin portal matches the latest published version on our changelog page to ensure it's up to date:

Downtime considerations

Gateways deployed within the same Site will automatically failover for each other. By upgrading Gateways one-by-one in a rolling update strategy, Clients connected to the Gateway being upgraded will automatically reconnect to an available Gateway.

Users may notice very brief interruptions to Resources for a few seconds as their Client reconnects to a healthy Gateway.