Merge pull request uselagoon#3620 from uselagoon/upgrade-paths

Docs: add upgrades and deprecations

DEPRECATIONS.md

@@ -1,33 +1,7 @@
 # Lagoon Project Deprecation Announcements
 
-## Overview
+Deprecations will be tracked by the release they are announced in, and then updated when the actual deprecation occurs. All deprecations should provide a rough timeline (in months or releases).
 
-This file is a constantly updated central tracker for deprecations across the suite of Lagoon products. As Lagoon continues to evolve, we occasionally need to replace, rename or retire existing processes, tools or configuration. Where this may impact a user's processes or procedures, we intend to outline a timeframe to allow any necessary changes to be made.
+## Deprecation and Upgrades policy
 
-Deprecations will be tracked by the release they are announced in, and then updated when the actual deprecation occurs. All deprecations should provide a rough timeline (in months or releases). Releases will normally only be listed here if they include planned deprecations.
-
-## Deprecation History
-
-All deprecations are listed below, with the most recent announcements at the top.
-
-### Lagoon v2.18.0
-release link: https://github.com/uselagoon/lagoon/releases/tag/v2.18.0
-* The standard drupal based tasks that Lagoon ships with (drush ....) have been flagged as deprecated and should not be used anymore. These will need to be replaced with [custom tasks](https://docs.lagoon.sh/using-lagoon-advanced/custom-tasks/). Example replacement tasks will be provided prior to their removal.
-* This release introduces a deprecation of the `setEnvironmentServices` mutation to updated services for an environment, it is being replaced with `addOrUpdateEnvironmentService` and `deleteEnvironmentService`. This is becaues the type is being refactored to support additional information, and eventually additional functionality. For now, the actions-handler service will still support the older `setEnvironmentServices` for backwards compatability for a short period to allow older versions of `lagoon-remote` to still work, but a new version of `lagoon-remote` will be available that will no longer provides the payload that the actions-handler uses.
-* The value for `registry` which was previously required by the `lagoon-core` chart is no longer required. If you are using this, you will need to add it under the new `unauthenticatedRegistry` setting when installing `lagoon-remote` in the `lagoon-build-deploy` section of your values file. If you aren't using an actual registry and have the example `disabled-only-use-harbor-via-deploy-controller.invalid` value, then you do not need to do anything except you can now remove the `registry` setting from your core values file.
-* The environment storage return field named `bytesUsed` is deprecated. The actual value stored is `kibibytes`. A new return field called `kibUsed` exists and should be used, the returned data is the same and both fields are still returned. `bytesUsed` will be removed in a future release, make any adjustments now to use `kibUsed`. This will be a breaking change in a future release.
-* `addOrUpdateEnvironmentStorage` is deprecated, `addOrUpdateStorageOnEnvironment` is the replacement to use as it supports the updated input value for `kibUsed`. `addOrUpdateEnvironmentStorage` will be completely removed in a future release.
-* The ability to configure projects to use different subsystems for managing deployments/tasks has been removed. Setting any values for the `activeSystems*` fields on the project will have no effect and the fields will be removed in a future release.
-
-### Lagoon v2.17.0
-
-release link: https://github.com/uselagoon/lagoon/releases/tag/v2.17.0
-* This release introduces a new active/standby task image that does not require the use of the [dioscuri controller](https://github.com/amazeeio/dioscuri). Dioscuri is deprecated and will eventually be removed from the `lagoon-remote` helm chart. If you use active/standby functionality in your clusters, you should upgrade to lagoon v2.17.0 and update your remote clusters to the version of the `lagoon-remote` helm chart the v2.17.0 release says to use (see release notes for v2.17.0)
-* Support for Harbor in the API will be removed in a future release. If you currently have your core installation with Harbor support, you should move to using the integration within lagoon-remote instead. See the documentation [here](https://docs.lagoon.sh/installing-lagoon/install-lagoon-remote) and read the section about Harbor.
-* Support for Harbor 2.1.x (chart version 1.5.x) and older in `lagoon-remote` will be removed in a future release. You should consider upgrading Harbor to a newer version (currently Lagoon supports up to v2.9.x (chart version 1.13.x)), following any recommended upgrade paths from Harbor.
-
-### Lagoon v2.16.0
-
-release link: https://github.com/uselagoon/lagoon/releases/tag/v2.16.0
-
-There were no planned deprecations announced in this release.
+See https://docs.lagoon.sh/releases/policy

UPGRADES.md

@@ -0,0 +1,9 @@
+# Lagoon Project Upgrades
+
+Whenever there is important information around versions of Lagoon that may impact the ability to upgrade to a new version, there will be upgrade information notes provided.
+
+You should always read all version release notes, upgrade notes, and deprecation notices for all versions you upgrade to.
+
+## Upgrades and Deprecation policy
+
+See https://docs.lagoon.sh/releases/policy

docs/releases/.pages

@@ -0,0 +1,5 @@
+title: Releases
+order: desc
+nav:
+  - Policy: policy.md
+  - ...

docs/releases/2.10.0.md

@@ -0,0 +1,14 @@
+#### Release Links
+* lagoon [v2.10.0](https://github.com/uselagoon/lagoon/releases/tag/v2.10.0)
+* lagoon-ui [core-v2.10.0](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.10.0)
+* lagoon-build-deploy [core-v2.10.0](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.10.0)
+* lagoon-core chart [1.12.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.12.0)
+
+## Upgrades
+
+### Upgrade to v2.9.x first
+You *must* upgrade to Lagoon v2.9.x before upgrading to v2.10.0. Ensure you read all the linked release notes.
+
+## Deprecations
+
+There are no required actions or considerations with this release

docs/releases/2.11.0.md

@@ -0,0 +1,18 @@
+#### Release Links
+* lagoon [v2.11.0](https://github.com/uselagoon/lagoon/releases/tag/v2.11.0)
+* lagoon-ui [core-v2.11.0](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.11.0)
+* lagoon-build-deploy [core-v2.11.0](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.11.0)
+* lagoon-core chart [1.16.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.16.0)
+
+## Upgrades
+
+### Upgrade to v2.10.x first
+You *must* upgrade to Lagoon v2.10.x before upgrading to v2.11.0. Ensure you read all the linked [release notes](./2.10.0.md#release-links).
+
+### Essential database backups
+Ensure you have a local backup of the api-db and keycloak-db before you commence this update, as there are complex migrations taking place in preparation for the v2.12.0 release.
+
+## Deprecations
+
+### Storage Calculator removed from core
+The storage-calculator service was removed from core in this release, and the service is now included in lagoon-remote.

docs/releases/2.12.0.md

@@ -0,0 +1,17 @@
+#### Release Links
+* lagoon [v2.12.0](https://github.com/uselagoon/lagoon/releases/tag/v2.12.0)
+* lagoon-ui [core-v2.12.0](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.12.0)
+* lagoon-build-deploy [core-v2.12.0](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.12.0)
+* lagoon-core chart [1.23.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.23.0)
+
+## Upgrades
+
+### Essential database backups
+Ensure you have a local backup of the api-db and keycloak-db before you commence this update. The update of these databases from MariaDB 10.4 to 10.6 should update seamlessly. In the event it does not go smoothly, the image cannot be rolled back owing to incompatible storage engines. You will need to drop the db and restore the backup to get running again.
+
+### Kubernetes 1.21 minimum requirement
+The minimum supported version of Kubernetes is 1.21 as of this release.
+
+## Deprecations
+
+There are no required actions or considerations with this release

docs/releases/2.13.0.md

@@ -0,0 +1,14 @@
+#### Release Links
+* lagoon [v2.13.0](https://github.com/uselagoon/lagoon/releases/tag/v2.13.0)
+* lagoon-ui [core-v2.13.0](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.13.0)
+* lagoon-build-deploy [core-v2.13.0](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.13.0)
+* lagoon-core chart [1.25.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.25.0)
+
+## Upgrades
+
+There are no required actions or considerations with this release. As always, we suggest upgrading all minor versions.
+
+## Deprecations
+
+### monitoring-urls
+The storage and use of monitoring-urls provided in lagoon.yml has been removed from the API.

docs/releases/2.14.0.md

@@ -0,0 +1,7 @@
+## Upgrades
+
+This tag was never released, and the [2.14.2](./2.14.2.md) release should be installed instead.
+
+## Deprecations
+
+This tag was never released, and the [2.14.2](./2.14.2.md) release should be installed instead.

docs/releases/2.14.1.md

@@ -0,0 +1,14 @@
+#### Release Links
+* lagoon [v2.14.2](https://github.com/uselagoon/lagoon/releases/tag/v2.14.2)
+* lagoon-ui [core-v2.14.2](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.14.2)
+* lagoon-build-deploy [core-v2.14.2](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.14.2)
+* lagoon-core chart [1.28.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.28.0)
+* lagoon-remote chart [0.76.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-remote-0.76.0)
+
+## Upgrades
+
+This release was superseded, and the [2.14.2](./2.14.2.md) release is recommended to be installed instead.
+
+## Deprecations
+
+This release was superseded, and the [2.14.2](./2.14.2.md) release is recommended to be installed instead.

docs/releases/2.14.2.md

@@ -0,0 +1,14 @@
+#### Release Links
+* lagoon [v2.14.2](https://github.com/uselagoon/lagoon/releases/tag/v2.14.2)
+* lagoon-ui [core-v2.14.2](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.14.2)
+* lagoon-build-deploy [core-v2.14.2](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.14.2)
+* lagoon-core chart [1.28.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.28.0)
+* lagoon-remote chart [0.76.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-remote-0.76.0)
+
+## Upgrades
+
+There are no required actions or considerations with this release. As always, we suggest upgrading all minor versions.
+
+## Deprecations
+
+There are no required actions or considerations with this release

docs/releases/2.15.0.md

@@ -0,0 +1,13 @@
+#### Release Links
+* lagoon [v2.15.0](https://github.com/uselagoon/lagoon/releases/tag/v2.15.0)
+* lagoon-ui [core-v2.15.0](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.15.0)
+* lagoon-build-deploy [core-v2.15.0](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.15.0)
+* lagoon-core chart [1.29.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.29.0)
+
+## Upgrades
+
+This release was superseded, and the [2.15.4](./2.15.4.md) release is recommended to be installed instead.
+
+## Deprecations
+
+This release was superseded, and the [2.15.4](./2.15.4.md) release is recommended to be installed instead.

docs/releases/2.15.1.md

@@ -0,0 +1,13 @@
+#### Release Links
+* lagoon [v2.15.1](https://github.com/uselagoon/lagoon/releases/tag/v2.15.1)
+* lagoon-ui [core-v2.15.1](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.15.1)
+* lagoon-build-deploy [core-v2.15.1](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.15.1)
+* lagoon-core chart [1.31.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.31.0)
+
+## Upgrades
+
+This release was superseded, and the [2.15.4](./2.15.4.md) release is recommended to be installed instead.
+
+## Deprecations
+
+This release was superseded, and the [2.15.4](./2.15.4.md) release is recommended to be installed instead.

docs/releases/2.15.2.md

@@ -0,0 +1,13 @@
+#### Release Links
+* lagoon [v2.15.2](https://github.com/uselagoon/lagoon/releases/tag/v2.15.2)
+* lagoon-ui [core-v2.15.2](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.15.2)
+* lagoon-build-deploy [core-v2.15.2](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.15.2)
+* lagoon-core chart [1.34.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.34.0)
+
+## Upgrades
+
+This release was superseded, and the [2.15.4](./2.15.4.md) release is recommended to be installed instead.
+
+## Deprecations
+
+This release was superseded, and the [2.15.4](./2.15.4.md) release is recommended to be installed instead.

docs/releases/2.15.3.md

@@ -0,0 +1,13 @@
+#### Release Links
+* lagoon [v2.15.3](https://github.com/uselagoon/lagoon/releases/tag/v2.15.3)
+* lagoon-ui [core-v2.15.3](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.15.3)
+* lagoon-build-deploy [core-v2.15.3](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.15.3)
+* lagoon-core chart [1.35.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.35.0)
+
+## Upgrades
+
+This release was superseded, and the [2.15.4](./2.15.4.md) release is recommended to be installed instead.
+
+## Deprecations
+
+This release was superseded, and the [2.15.4](./2.15.4.md) release is recommended to be installed instead.

docs/releases/2.15.4.md

@@ -0,0 +1,13 @@
+#### Release Links
+* lagoon [v2.15.4](https://github.com/uselagoon/lagoon/releases/tag/v2.15.4)
+* lagoon-ui [core-v2.15.4](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.15.4)
+* lagoon-build-deploy [core-v2.15.4](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.15.4)
+* lagoon-core chart [1.36.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.36.0)
+
+## Upgrades
+
+There are no required actions or considerations with this release. As always, we suggest upgrading all minor versions.
+
+## Deprecations
+
+There are no required actions or considerations with this release

docs/releases/2.16.0.md

@@ -0,0 +1,13 @@
+#### Release Links
+* lagoon [v2.16.0](https://github.com/uselagoon/lagoon/releases/tag/v2.16.0)
+* lagoon-ui [core-v2.16.0](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.16.0)
+* lagoon-build-deploy [core-v2.16.0](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.16.0)
+* lagoon-core chart [1.37.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.37.0)
+
+## Upgrades
+
+There are no required actions or considerations with this release. As always, we suggest upgrading all minor versions.
+
+## Deprecations
+
+There are no required actions or considerations with this release

docs/releases/2.17.0.md

@@ -0,0 +1,19 @@
+#### Release Links
+* lagoon [v2.17.0](https://github.com/uselagoon/lagoon/releases/tag/v2.17.0)
+* lagoon-ui [core-v2.17.0](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.17.0)
+* lagoon-build-deploy [core-v2.17.0](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.17.0)
+* lagoon-core chart [1.41.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.41.0)
+* lagoon-remote chart [0.87.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-remote-0.87.0)
+
+## Upgrades
+
+There are no required actions or considerations with this release. As always, we suggest upgrading all minor versions.
+
+## Deprecations
+
+### activestandby task image
+* This release introduces a new active/standby task image that does not require the use of the [dioscuri controller](https://github.com/amazeeio/dioscuri). Dioscuri is deprecated and will eventually be removed from the `lagoon-remote` helm chart. If you use active/standby functionality in your clusters, you should upgrade to lagoon v2.17.0 and update your remote clusters to the version of the `lagoon-remote` helm chart the v2.17.0 release says to use (see release notes for v2.17.0)
+### API Harbor support
+* Support for Harbor in the API will be removed in a future release. If you currently have your core installation with Harbor support, you should move to using the integration within lagoon-remote instead. See the documentation [here](https://docs.lagoon.sh/installing-lagoon/install-lagoon-remote) and read the section about Harbor.
+### Harbor 2.1 and earlier support
+* Support for Harbor 2.1.x (chart version 1.5.x) and older in `lagoon-remote` will be removed in a future release. You should consider upgrading Harbor to a newer version (currently Lagoon supports up to v2.9.x (chart version 1.13.x)), following any recommended upgrade paths from Harbor.

docs/releases/2.18.0.md

@@ -0,0 +1,24 @@
+#### Release Links
+* lagoon [v2.18.0](https://github.com/uselagoon/lagoon/releases/tag/v2.18.0)
+* lagoon-ui [core-v2.18.0](https://github.com/uselagoon/lagoon-ui/releases/tag/core-v2.18.0)
+* lagoon-build-deploy [core-v2.18.0](https://github.com/uselagoon/build-deploy-tool/releases/tag/core-v2.18.0)
+* lagoon-core chart [1.42.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-core-1.42.0)
+* lagoon-remote chart [0.88.0](https://github.com/uselagoon/lagoon-charts/releases/tag/lagoon-remote-0.88.0)
+
+## Upgrades
+There are no required actions or considerations with this release. As always, we suggest upgrading all minor versions.
+
+## Deprecations
+
+### In-built Drupal Tasks
+* The standard drupal based tasks that Lagoon ships with (Drush ....) have been flagged as deprecated and should not be used anymore. These will need to be replaced with [custom tasks](https://docs.lagoon.sh/using-lagoon-advanced/custom-tasks/). Example replacement tasks will be provided prior to their removal.
+### setEnvironmentServices
+* This release introduces a deprecation of the `setEnvironmentServices` mutation to updated services for an environment, it is being replaced with `addOrUpdateEnvironmentService` and `deleteEnvironmentService`. This is because the type is being refactored to support additional information, and eventually additional functionality. For now, the actions-handler service will still support the older `setEnvironmentServices` for backwards compatibility for a short period to allow older versions of `lagoon-remote` to still work, but a new version of `lagoon-remote` will be available that will no longer provides the payload that the actions-handler uses.
+### Core Registry variable
+* The value for `registry` which was previously required by the `lagoon-core` chart is no longer required. If you are using this, you will need to add it under the new `unauthenticatedRegistry` setting when installing `lagoon-remote` in the `lagoon-build-deploy` section of your values file. If you aren't using an actual registry and have the example `disabled-only-use-harbor-via-deploy-controller.invalid` value, then you do not need to do anything except you can now remove the `registry` setting from your core values file.
+### bytesUsed
+* The environment storage return field named `bytesUsed` is deprecated. The actual value stored is `kibibytes`. A new return field called `kibUsed` exists and should be used, the returned data is the same and both fields are still returned. `bytesUsed` will be removed in a future release, make any adjustments now to use `kibUsed`. This will be a breaking change in a future release.
+### addOrUpdateEnvironmentStorage
+* `addOrUpdateEnvironmentStorage` is deprecated, `addOrUpdateStorageOnEnvironment` is the replacement to use as it supports the updated input value for `kibUsed`. `addOrUpdateEnvironmentStorage` will be completely removed in a future release.
+### activesystems
+* The ability to configure projects to use different subsystems for managing deployments/tasks has been removed. Setting any values for the `activeSystems*` fields on the project will have no effect and the fields will be removed in a future release.