From c07173006fbea2f2e68f99db3cd9169c26d2b3e5 Mon Sep 17 00:00:00 2001 From: Thomas Eizinger Date: Wed, 30 Jul 2025 09:14:02 +0000 Subject: [PATCH] docs: describe version compatibility between components (#10041) First draft of documenting the versioning scheme that we have been following. --------- Signed-off-by: Thomas Eizinger Co-authored-by: Jamil --- .../app/kb/administer/upgrading/readme.mdx | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/website/src/app/kb/administer/upgrading/readme.mdx b/website/src/app/kb/administer/upgrading/readme.mdx index 4feed7139..1ff06758d 100644 --- a/website/src/app/kb/administer/upgrading/readme.mdx +++ b/website/src/app/kb/administer/upgrading/readme.mdx @@ -17,6 +17,29 @@ upgrade your Gateway for both Docker and systemd deployments. platform. +## 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