docs: describe version compatibility between components (#10041)

First draft of documenting the versioning scheme that we have been
following.

---------

Signed-off-by: Thomas Eizinger <thomas@eizinger.io>
Co-authored-by: Jamil <jamilbk@users.noreply.github.com>
This commit is contained in:
Thomas Eizinger
2025-07-30 09:14:02 +00:00
committed by GitHub
parent 47703b4029
commit c07173006f

View File

@@ -17,6 +17,29 @@ upgrade your Gateway for both Docker and systemd deployments.
platform.
</Alert>
## 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