docs: reword 222 release notes

docs/releases/2.22.0.md

@@ -11,10 +11,29 @@ This release is a standard Lagoon release. There are changes required for teams
 
 ## Upgrades
 
-Self-managed Lagoon installs will need to be aware of three changes in lagoon-core and lagoon-remote
-* https://github.com/uselagoon/lagoon-charts/pull/602 updates the version of NATS, which requires a couple of straightforward config structure changes in lagoon-core and lagoon-remote. THere are no changes to the certs  or keys, just the naming of the YAML items
-* https://github.com/uselagoon/lagoon-charts/pull/688 introduces a new version of the lagoon build and task CRDs - after installing lagoon-remote, you will need to apply the new CRDs for builds and tasks to work - e.g. `helm show crds lagoon/lagoon-build-deploy --version 0.30.2 | kubectl apply -f -`
-* https://github.com/uselagoon/lagoon-charts/pull/687 converted the docker-host to a StatefulSet - which allows for multiple replicas to be specified - this will provide some load-balancing of docker workloads. It will result in a new docker-host cache being created the first time any replica starts up (including on the first deployment) - this may result in the first few builds being less-optimized whilst the cache rebuilds.
+Self-managed Lagoon installs will need to be aware of three changes in lagoon-core and lagoon-remote. Please read the following sections carefully to ensure you update components that apply to your installation correctly.
+
+### Lagoon Custom Resource Definitions (CRDs)
+
+We introduced a new API version of the Lagoon Build and Task CRDs in https://github.com/uselagoon/lagoon-charts/pull/688. You must upgrade these after installing the latest version of `lagoon-remote`. Failure to update the CRDs will result in the remote controller failing to start, or builds and tasks failing.
+
+If you're installing the version defined in the top of these release notes, you can use the following to upgrade the CRDs to the version required.
+
+```
+helm show crds lagoon/lagoon-build-deploy --version 0.30.2 | kubectl apply -f -
+```
+
+Alternatively, see the [README in the lagoon-build-deploy chart](https://github.com/uselagoon/lagoon-charts/blob/main/charts/lagoon-build-deploy/README.md#lagoon-remote) for further examples on how to update the Lagoon Build and Task CRDs.
+
+### DockerHost StatefulSet
+
+To help with improving or distributing build loads, we converted the docker-host from a `Deployment` to a `StatefulSet` in https://github.com/uselagoon/lagoon-charts/pull/687. This allows the docker-host to be scaled.
+
+This will provide the ability to load-balance docker build workloads. It will result in a new docker-host cache being created the first time any replica starts up (including on the first deployment), this may result in the first few builds being less-optimized whilst the cache rebuilds. This StatefulSet must only be scaled up or down via helm, and not directly in kubernetes otherwise the load-balancing of the workloads will not be able to be fully utilised.
+
+### NATS / SSH Portal
+
+The version of NATS used by Lagoon was updated in https://github.com/uselagoon/lagoon-charts/pull/602. If your installation of Lagoon utilises SSH portals and NATS, you need to be aware of changes to the structure of the NATS values. This upgrade requires minimal config structure changes in your lagoon-core and lagoon-remote values files. There are no changes to the certs or keys, just the naming of the YAML items. See the pullrequest description for more information.
 
 ## Deprecations