docs(self-managed): upgrade instractions fo components moved to top-l…

…evel in v8.5 (#3490)

* docs(self-managed): upgrade instractions fo components moved to top-level in v8.5

* style(formatting): technical review

---------

Co-authored-by: Christina Ausley <[email protected]>

docs/self-managed/operational-guides/update-guide/840-to-850.md

@@ -6,6 +6,14 @@ description: "Review which adjustments must be made to migrate from Camunda 8.4.
 
 The following sections explain which adjustments must be made to migrate from Camunda 8.4.x to 8.5.x for each component.
 
+## Helm chart
+
+:::caution Breaking changes
+The Camunda Helm chart v10.0.0 that comes with Camunda 8.5 has major changes in the values file structure. Update the values keys before starting the chart upgrade.
+:::
+
+Carefully follow the [upgrade instructions](../../platform-deployment/helm-kubernetes/upgrade.md#v1000) to upgrade from Camunda Helm chart v9.x.x to Camunda Helm chart v10.x.x.
+
 ## Zeebe
 
 ### Deprecated broker health checks

docs/self-managed/platform-deployment/helm-kubernetes/upgrade.md

@@ -80,9 +80,9 @@ helm upgrade camunda camunda/camunda-platform\
   --set global.identity.auth.operate.existingSecret=$OPERATE_SECRET \
   --set global.identity.auth.connectors.existingSecret=$CONNECTORS_SECRET \
   --set global.identity.auth.zeebe.existingSecret=$ZEEBE_SECRET \
-  --set identity.keycloak.auth.adminPassword=$KEYCLOAK_ADMIN_SECRET \
-  --set identity.keycloak.auth.managementPassword=$KEYCLOAK_MANAGEMENT_SECRET \
-  --set identity.keycloak.postgresql.auth.password=$POSTGRESQL_SECRET
+  --set identityKeycloak.auth.adminPassword=$KEYCLOAK_ADMIN_SECRET \
+  --set identityKeycloak.auth.managementPassword=$KEYCLOAK_MANAGEMENT_SECRET \
+  --set identityKeycloak.postgresql.auth.password=$POSTGRESQL_SECRET
 ```
 
 :::note
@@ -93,8 +93,98 @@ For more details on the Keycloak upgrade path, you can also read the [Bitnami Ke
 
 ## Version update instructions
 
+### v10.0.0
+
+Camunda Release Cycle: 8.5
+
+:::caution Breaking changes
+The Camunda Helm chart v10.0.0 has major changes in the values file structure. Follow the upgrade steps for each component before starting the chart upgrade.
+:::
+
+#### Identity
+
+The Camunda Identity component was formerly a sub-chart of the Camunda Helm chart. Now, it is part of the parent Camunda Helm chart.
+
+There are no changes in the Identity keys, but since the `LabelSelector` `MatchLabels` of a Kubernetes resource are immutable, its deployment should be deleted as the label `app.kubernetes.io/name` has been changed from `identity` to `camunda-platform`.
+
+```shell
+kubectl -n camunda delete -l app.kubernetes.io/name=identity deployment
+```
+
+#### Identity - Keycloak
+
+The Identity Keycloak values key has been changed from `identity.keycloak` to `identityKeycloak`.
+To migrate, move the values under the new key in the values file.
+
+Old:
+
+```yaml
+identity:
+  keycloak:
+```
+
+New:
+
+```yaml
+identityKeycloak:
+```
+
+#### Identity - PostgreSQL
+
+The Identity PostgreSQL values key has been changed from `identity.postgresql` to `identityPostgresql`.
+To migrate, move the values under the new key in the values file.
+
+Old:
+
+```yaml
+identity:
+  postgresql:
+```
+
+New:
+
+```yaml
+identityPostgresql:
+```
+
+#### Web Modeler - PostgreSQL
+
+The WebModler PostgreSQL values key has been changed from `postgresql` to `webModelerPostgresql`.
+To migrate, move the values under the new key in the values file.
+
+Old:
+
+```yaml
+postgresql:
+```
+
+New:
+
+```yaml
+webModelerPostgresql:
+```
+
+#### Zeebe Gateway
+
+The Zeebe Gateway values key has been changed from `zeebe-gateway` to `zeebeGateway`.
+To migrate, move the values under the new key in the values file.
+
+Old:
+
+```yaml
+zeebe-gateway:
+```
+
+New:
+
+```yaml
+zeebeGateway:
+```
+
 ### v9.3.0
 
+Camunda Release Cycle: 8.4
+
 #### Enabling Console
 
 When enabling Console for the first time, you may see the following error:
@@ -117,6 +207,8 @@ You should now be able to log into Console.
 
 ### v9.0.0
 
+Camunda Release Cycle: 8.4
+
 For full change log, view the Camunda Helm chart [v9.0.0 release notes](https://github.com/camunda/camunda-platform-helm/releases/tag/camunda-platform-9.0.0).
 
 #### Helm chart
@@ -147,6 +239,8 @@ Elasticsearch image has been upgraded from 8.8.2 to 8.9.2.
 
 ### v8.3.1
 
+Camunda Release Cycle: 8.3
+
 :::caution
 The following steps are applied when upgrading from **any** previous version, including `8.3.0`.
 :::
@@ -176,6 +270,8 @@ The following resources have been renamed:
 
 ### v8.3.0 (minor)
 
+Camunda Release Cycle: 8.3
+
 :::caution
 Updating Operate, Tasklist, and Optimize from 8.2.x to 8.3.0 will potentially take longer than expected, depending on the data to be migrated.
 Additionally, we identified some bugs that could also prevent the migration from succeeding. These are being addressed and will be available in an upcoming 8.3.1 patch. We suggest not updating until the patch is released.
@@ -406,6 +502,8 @@ webModeler:
 
 ### v8.2.9
 
+Camunda Release Cycle: 8.2
+
 #### Optimize
 
 For Optimize 3.10.1, a new environment variable introduced redirection URL. However, the change is not compatible with Camunda Helm charts until it is fixed in 3.10.3 (and Helm chart 8.2.9). Therefore, those versions are coupled to certain Camunda Helm chart versions:
@@ -419,6 +517,8 @@ No action is needed if you use Optimize 3.10.3 (shipped with this Helm chart ver
 
 ### v8.2.3
 
+Camunda Release Cycle: 8.2
+
 #### Zeebe Gateway
 
 :::caution Breaking change
@@ -438,6 +538,8 @@ To authenticate:
 
 ### v8.2.0 (Minor)
 
+Camunda Release Cycle: 8.2
+
 #### Connectors
 
 Camunda 8 Connectors component is one of our applications which performs the integration with an external system.
@@ -555,6 +657,8 @@ Then follow the [typical upgrade steps](#upgrading-where-identity-enabled).
 
 ### v8.0.13
 
+Camunda Release Cycle: 8.0
+
 If you installed Camunda 8 using Helm charts before `8.0.13`, you need to apply the following steps to handle the new Elasticsearch labels.
 
 As a prerequisite, make sure you have the Elasticsearch Helm repository added: