diff --git a/docs/self-managed/setup/upgrade.md b/docs/self-managed/setup/upgrade.md index 586daaaa0e..98cae29cdf 100644 --- a/docs/self-managed/setup/upgrade.md +++ b/docs/self-managed/setup/upgrade.md @@ -2,120 +2,52 @@ id: upgrade title: "Camunda 8 Helm upgrade" sidebar_label: "Upgrade" -description: "To upgrade to a more recent version of the Camunda Helm charts, there are certain things you need to keep in mind." +description: "Upgrade to a more recent version of the Camunda Helm charts, and view configuration changes between versions." --- -To upgrade to a more recent version of the Camunda Helm charts, configuration adjustments may be required. Review the [instructions for specific versions](#version-update-instructions) prior to starting an upgrade. +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; :::note -The recommended Helm upgrade path is to the **latest patch** release of the **next major version**. +When upgrading to a new version of the Camunda 8 Helm charts, we recommend updating to the **latest patch** release of the **next major version**. ::: -### Upgrading where Identity disabled +Upgrading between minor versions of the Camunda Helm chart may require [configuration changes](#update-your-configuration). To upgrade between patch versions or when no configuration changes are required, see the [`helm upgrade`](#identity-disabled) instructions. -Normally for a Helm upgrade, you run the [Helm upgrade](https://helm.sh/docs/helm/helm_upgrade/) command. If you have disabled Camunda Identity and the related authentication mechanism, you should be able to do an upgrade as follows: +## Upgrade requirements -```shell -helm upgrade camunda -``` - -However, if Camunda Identity is enabled (which is the default), the upgrade path is a bit more complex than just running `helm upgrade`. Read the next section to familiarize yourself with the upgrade process. - -### Upgrading where Identity enabled - -If you have installed the Camunda 8 Helm charts before with default values, this means Identity and the related authentication mechanism are enabled. For authentication, the Helm charts generate the secrets randomly if not specified on installation for each web application. If you run `helm upgrade` to upgrade to a newer chart version, you likely will see the following return: - -```shell -helm upgrade camunda-platform-test camunda/camunda-platform -``` - -You likely will see the following error: - -```shell -Error: UPGRADE FAILED: execution error at (camunda-platform/charts/identity/templates/tasklist-secret.yaml:10:22): -PASSWORDS ERROR: You must provide your current passwords when upgrading the release. - Note that even after reinstallation, old credentials may be needed as they may be kept in persistent volume claims. - Further information can be obtained at https://docs.bitnami.com/general/how-to/troubleshoot-helm-chart-issues/#credential-errors-while-upgrading-chart-releases - - 'global.identity.auth.tasklist.existingSecret' must not be empty, please add '--set global.identity.auth.tasklist.existingSecret=$TASKLIST_SECRET' to the command. To get the current value: - - export TASKLIST_SECRET=$(kubectl get secret --namespace "camunda" "camunda-platform-test-tasklist-identity-secret" -o jsonpath="{.data.tasklist-secret}" | base64 --decode) -``` - -As mentioned, this output returns because secrets are randomly generated with the first Helm installation by default if not further specified. We use a library chart [provided by Bitnami](https://github.com/bitnami/charts/tree/master/bitnami/common) for this. The generated secrets persist on persistent volume claims (PVCs), which are not maintained by Helm. - -If you remove the Helm chart release or do an upgrade, PVCs are not removed nor recreated. On an upgrade, secrets can be recreated by Helm and could lead to the regeneration of the secret values. This would mean that newly generated secrets would no longer match with the persistent secrets. To avoid such an issue, Bitnami blocks the upgrade path and prints the help message as shown above. - -In the error message, Bitnami links to their [troubleshooting guide](https://docs.bitnami.com/general/how-to/troubleshoot-helm-chart-issues/#credential-errors-while-upgrading-chart-releases). However, to avoid confusion, we will step through the troubleshooting process in this guide as well. - -### Secrets extraction +For a smooth upgrade experience, we recommend determining both your **Helm chart** and **Helm CLI** versions prior to starting your upgrade. -For a successful upgrade, you first need to extract all secrets that were previously generated. +### Helm chart version -:::note - -The following is meant as a sample script to build upon. Be sure to adapt the following script to your specific configuration. For example, when using an Identity provider other than Keycloak, the Keycloak-related secrets listed are unnecessary. It will likely be necessary to change this script to account for the secrets found in your specific environment. +As of the Camunda 8.4 release, the Camunda 8 **Helm chart** version is independent from the application version (for example, the Camunda 8.4 release uses the Helm chart version 9.0.0). The Helm chart is updated with each application release. -::: +Review the Camunda 8 Helm chart [version matrix](https://helm.camunda.io/camunda-platform/version-matrix/) to determine the application and Helm chart versions of your installation. -To extract the secrets, use the following code snippet. Make sure to replace `camunda` with your actual Helm release name. +You can also view all chart versions and application versions via the Helm CLI: ```shell -# Uncomment if Console is enabled. -# export CONSOLE_SECRET=$(kubectl get secret "camunda-console-identity-secret" -o jsonpath="{.data.console-secret}" | base64 --decode) -export TASKLIST_SECRET=$(kubectl get secret "camunda-tasklist-identity-secret" -o jsonpath="{.data.tasklist-secret}" | base64 --decode) -export OPTIMIZE_SECRET=$(kubectl get secret "camunda-optimize-identity-secret" -o jsonpath="{.data.optimize-secret}" | base64 --decode) -export OPERATE_SECRET=$(kubectl get secret "camunda-operate-identity-secret" -o jsonpath="{.data.operate-secret}" | base64 --decode) -export CONNECTORS_SECRET=$(kubectl get secret "camunda-connectors-identity-secret" -o jsonpath="{.data.connectors-secret}" | base64 --decode) -export ZEEBE_SECRET=$(kubectl get secret "camunda-zeebe-identity-secret" -o jsonpath="{.data.zeebe-secret}" | base64 --decode) -export KEYCLOAK_ADMIN_SECRET=$(kubectl get secret "camunda-keycloak" -o jsonpath="{.data.admin-password}" | base64 --decode) -export KEYCLOAK_MANAGEMENT_SECRET=$(kubectl get secret "camunda-keycloak" -o jsonpath="{.data.management-password}" | base64 --decode) -export POSTGRESQL_SECRET=$(kubectl get secret "camunda-postgresql" -o jsonpath="{.data.postgres-password}" | base64 --decode) -``` - -After exporting all secrets into environment variables, run the following upgrade command: - -```shell -helm upgrade camunda camunda/camunda-platform \ - # Uncomment if Console is enabled. - # --set global.identity.auth.console.existingSecret=$CONSOLE_SECRET \ - --set global.identity.auth.tasklist.existingSecret=$TASKLIST_SECRET \ - --set global.identity.auth.optimize.existingSecret=$OPTIMIZE_SECRET \ - --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 identityKeycloak.auth.adminPassword=$KEYCLOAK_ADMIN_SECRET \ - --set identityKeycloak.auth.managementPassword=$KEYCLOAK_MANAGEMENT_SECRET \ - --set identityKeycloak.postgresql.auth.password=$POSTGRESQL_SECRET +helm search repo camunda/camunda-platform --versions ``` -:::note +### Helm CLI version -If you have specified on the first installation certain values, you have to specify them again on the upgrade either via `--set` or the values file and the `-f` flag. +Use the recommended Helm CLI version for your Helm chart when upgrading. The Helm CLI version for each chart can be found on the [chart version matrix](https://helm.camunda.io/camunda-platform/version-matrix/). -::: +## Update your configuration -For more details on the Keycloak upgrade path, you can also read the [Keycloak Upgrading Guide](https://www.keycloak.org/docs/latest/upgrading/). +Configuration adjustments may be required when upgrading to a new version of the Helm chart. Before beginning your upgrade, ensure you have implemented any changes required by your new version. -## Version update instructions + -As of the 8.4 release, the Camunda 8 **Helm chart** version is decoupled from the version of the application. The Helm chart release still follows the applications release cycle, but it has an independent version. (e.g., in the application release cycle 8.4, the chart version is 9.0.0). - -For more details about the applications version included in the Helm chart, review the [full version matrix](https://helm.camunda.io/camunda-platform/version-matrix/). - -You can also view all chart versions and application versions via Helm CLI as follows: - -```shell -helm search repo camunda/camunda-platform --versions -``` - -**After applying the instructions for each Helm chart, get back to the top of this page and start the upgrade process. ** - -## Helm CLI version - -For a smooth upgrade, always use the same Helm CLI version corresponding with the chart version that shows in the [chart version matrix](https://helm.camunda.io/camunda-platform/version-matrix/). - -## From Camunda 8.5 to 8.6 + ### Helm chart 11.0.0+ @@ -150,9 +82,11 @@ The following keys were deprecated in 8.5, and their removal has been delayed un The separated Ingress Helm configuration has been deprecated in 8.6, and will be removed from the Helm chart in 8.7. If using a separated Ingress, switch to a [combined Ingress](/self-managed/setup/guides/ingress-setup.md) to ensure a smooth upgrade experience. -## From Camunda 8.4 to 8.5 + + + -### Helm chart 10.2.0+ +

Helm chart 10.2.0+

As of this Helm chart version, the image tags for all components are independent, and do not reference the global image tag. The value of the key `global.image.tag` is `null`, and each component now sets its own version. @@ -160,7 +94,7 @@ With this change, Camunda applications no longer require a unified patch version The key `global.image.tag` is deprecated and it will be removed in the Camunda 8.6 release. -### Helm chart 10.0.2+ +

Helm chart 10.0.2+

The upgrade path for Camunda Helm Chart v9.x.x is v10.0.2+. @@ -281,9 +215,11 @@ In v10.0.0, it is possible to use external Elasticsearch. For more information o In v10.0.0, it is possible to use external OpenSearch. For more information on how to set up external OpenSearch, refer to [using external OpenSearch](./guides/using-existing-opensearch.md). -## From Camunda 8.3 to 8.4 + -### Helm Chart 9.3.0 + + +

Helm Chart 9.3.0

#### Enabling Console @@ -305,7 +241,7 @@ To add the Console role: You should now be able to log into Console. -### Helm Chart 9.0.0 +

Helm Chart 9.0.0

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). @@ -335,9 +271,11 @@ The embedded Keycloak Helm chart has been upgraded from 16.1.7 to 17.3.6 (only t Elasticsearch image has been upgraded from 8.8.2 to 8.9.2. -## From Camunda 8.2 to 8.3 + + + -### Helm Chart 8.3.1 +

Helm Chart 8.3.1

:::caution The following steps are applied when upgrading from **any** previous version, including `8.3.0`. @@ -366,7 +304,7 @@ The following resources have been renamed: - **ConfigMap:** From `camunda-zeebe-gateway-gateway` to `camunda-zeebe-gateway`. - **ServiceAccount:** From `camunda-zeebe-gateway-gateway` to `camunda-zeebe-gateway`. -### Helm Chart 8.3.0 (minor) +

Helm Chart 8.3.0 (minor)

:::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. @@ -596,230 +534,82 @@ webModeler: url: "jdbc:postgresql://web-modeler-postgres-ext:5432/rest-api-db" ``` -## From Camunda 8.1 to 8.2 - -### Helm Chart 8.2.9 - -#### 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: - -| Optimize version | Camunda Helm chart version | -| --------------------------------- | -------------------------- | -| Optimize 3.10.1 & Optimize 3.10.2 | 8.2.0 - 8.2.8 | -| Optimize 3.10.3 | 8.2.9+ | - -No action is needed if you use Optimize 3.10.3 (shipped with this Helm chart version by default), but this Optimize version cannot be used out of the box with previous Helm chart versions. - -### Helm Chart 8.2.3 - -#### Zeebe Gateway - -:::caution Breaking change - -Zeebe Gateway authentication is now enabled by default. - -::: - -To authenticate: - -1. [Create a client credential](/guides/setup-client-connection-credentials.md). -2. [Assign permissions to the application](/self-managed/identity/user-guide/authorizations/managing-resource-authorizations.md). -3. Connect with: - -- [Desktop Modeler](/components/modeler/desktop-modeler/connect-to-camunda-8.md). -- [Zeebe client (zbctl)](/self-managed/zeebe-deployment/security/secure-client-communication.md#zbctl). - -### Helm Chart 8.2.0 (Minor) - -#### Connectors - -Camunda 8 Connectors component is one of our applications which performs the integration with an external system. - -Currently, in all cases, either you will use Connectors v8.2 or not, this step should be done. You need to create the Connectors secret object (more details about this in [camunda-platform-helm/656](https://github.com/camunda/camunda-platform-helm/issues/656)). - -First, generate the Connectors secret: - -```shell -helm template camunda camunda/camunda-platform --version 8.2 \ - --show-only charts/identity/templates/connectors-secret.yaml > - identity-connectors-secret.yaml -``` - -Then apply it: - -```shell -kubectl apply --namespace -f identity-connectors-secret.yaml -``` - -#### Keycloak - -Camunda v8.2 uses Keycloak v19 which depends on PostgreSQL v15. That is a major change for the dependencies. Currently there are two recommended options to upgrade from Camunda 8.1.x to 8.2.x: - -1. Use the previous version of PostgreSQL v14 in Camunda v8.2, this should be simple and it will work seamlessly. -2. Follow the official PostgreSQL upgrade guide: [Upgrading a PostgreSQL Cluster v15](https://www.postgresql.org/docs/15/upgrading.html). However, it requires some manual work and longer downtime to do the database schema upgrade. - -**Method 1: Use the previous version PostgreSQL v14** - -You can set the PostgreSQL image tag as follows: - -```yaml -identity: - keycloak: - postgresql: - image: - tag: 14.5.0 -``` - -Then follow the [typical upgrade steps](#upgrading-where-identity-enabled). - -**Method 2: Upgrade the database schema to work with PostgreSQL v15** - -The easiest way to upgrade major versions of postgresql is to start a port-forward, -and then run `pg_dump` or `pg_restore`. The postgresql client versions are fairly flexible -with different server versions, but for best results, we recommend using the newest -client version. - -1. In one terminal, start a `port-forward` against the postgresql service: - -```shell -kubectl port-forward svc/camunda-postgresql 5432 -``` - -Follow the rest of these steps in a different terminal. - -2. Get the 'postgres' users password from the postgresql service: - -```shell -kubectl exec -it statefulset/camunda-postgresql -- env | grep "POSTGRES_POSTGRES_PASSWORD=" -``` - -3. Scale identity down using the following command: - -```shell -kubectl scale --replicas=0 deployment camunda-identity -``` + -4. Perform the database dump: + -```shell -pg_dumpall -U postgres -h localhost -p 5432 | tee dump.psql -Password: -``` +## Upgrade Camunda -`pg_dumpall` may ask multiple times for the same password. The database will be dumped into `dump.psql`. +If you have installed the Camunda 8 Helm charts before with default values, Identity and the related authentication mechanism are enabled. If you have disabled Identity, see how to upgrade Camunda [with Identity disabled](#identity-disabled). -5. Scale database down using the following command: +### Identity enabled -```shell -kubectl scale --replicas=0 statefulset camunda-postgresql -``` +#### Extract secrets -6. Delete the PVC for the postgresql instance using the following command: +If not specified on installation, the Helm chart generates random secrets for all components (including Keycloak). To upgrade successfully, these secrets must be extracted and provided during your upgrade. -```shell -kubectl delete pvc data-camunda-postgresql-0 -``` - -7. Update the postgresql version using the following command: - -```shell -kubectl set image statefulset/camunda-postgresql postgresql=docker.io/bitnami/postgresql:15.3.0 -``` - -8. Scale the services back up using the following command: +To extract the secrets, use the following code snippet, replacing `camunda` with your actual Helm release name: ```shell -kubectl scale --replicas=1 statefulset camunda-postgresql -``` - -9. Restore the database dump using the following command: - -```shell -psql -U postgres -h localhost -p 5432 -f dump.psql -``` - -10. Scale up identity using the following command: - -```shell -kubectl scale --replicas=1 deployment camunda-identity +# Uncomment if Console is enabled. +# export CONSOLE_SECRET=$(kubectl get secret "camunda-console-identity-secret" -o jsonpath="{.data.console-secret}" | base64 --decode) +export TASKLIST_SECRET=$(kubectl get secret "camunda-tasklist-identity-secret" -o jsonpath="{.data.tasklist-secret}" | base64 --decode) +export OPTIMIZE_SECRET=$(kubectl get secret "camunda-optimize-identity-secret" -o jsonpath="{.data.optimize-secret}" | base64 --decode) +export OPERATE_SECRET=$(kubectl get secret "camunda-operate-identity-secret" -o jsonpath="{.data.operate-secret}" | base64 --decode) +export CONNECTORS_SECRET=$(kubectl get secret "camunda-connectors-identity-secret" -o jsonpath="{.data.connectors-secret}" | base64 --decode) +export ZEEBE_SECRET=$(kubectl get secret "camunda-zeebe-identity-secret" -o jsonpath="{.data.zeebe-secret}" | base64 --decode) +export KEYCLOAK_ADMIN_SECRET=$(kubectl get secret "camunda-keycloak" -o jsonpath="{.data.admin-password}" | base64 --decode) +export KEYCLOAK_MANAGEMENT_SECRET=$(kubectl get secret "camunda-keycloak" -o jsonpath="{.data.management-password}" | base64 --decode) +export POSTGRESQL_SECRET=$(kubectl get secret "camunda-postgresql" -o jsonpath="{.data.postgres-password}" | base64 --decode) ``` -Then follow the [typical upgrade steps](#upgrading-where-identity-enabled). - -## From Camunda 8.0 to 8.1 - -No Helm chart upgrade instructions for this version. +#### Run `helm upgrade` -## From Camunda 1.3 to 8.0 - -### Helm Chart 8.0.13 - -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: +After exporting all secrets into environment variables, run the following upgrade command: ```shell -helm repo add elastic https://helm.elastic.co +helm upgrade camunda camunda/camunda-platform \ + # Uncomment if Console is enabled. + # --set global.identity.auth.console.existingSecret=$CONSOLE_SECRET \ + --set global.identity.auth.tasklist.existingSecret=$TASKLIST_SECRET \ + --set global.identity.auth.optimize.existingSecret=$OPTIMIZE_SECRET \ + --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 identityKeycloak.auth.adminPassword=$KEYCLOAK_ADMIN_SECRET \ + --set identityKeycloak.auth.managementPassword=$KEYCLOAK_MANAGEMENT_SECRET \ + --set identityKeycloak.postgresql.auth.password=$POSTGRESQL_SECRET ``` -#### 1. Retain Elasticsearch Persistent Volume +If you have set secret values on installation, you must specify them again on the upgrade either via `--set`, as demonstrated above, or by passing in a values file using the `-f` flag. -First, get the name of Elasticsearch Persistent Volumes: - -```shell -ES_PV_NAME0=$(kubectl get pvc elasticsearch-master-elasticsearch-master-0 -o jsonpath="{.spec.volumeName}") +:::note +For more details on the Keycloak upgrade path, see the [Keycloak upgrade guide](https://www.keycloak.org/docs/latest/upgrading/). +::: -ES_PV_NAME1=$(kubectl get pvc elasticsearch-master-elasticsearch-master-1 -o jsonpath="{.spec.volumeName}") -``` +### Identity disabled -Make sure these are the correct Persistent Volumes: +If you have **disabled** Camunda Identity and the related authentication mechanism, Camunda can be upgraded with the following command: ```shell -kubectl get persistentvolume $ES_PV_NAME0 $ES_PV_NAME1 -``` - -It should show something like the following (note the name of the claim, it's for Elasticsearch): - -``` -NAME CAPACITY ACCESS MODES RECLAIM POLICY STATUS CLAIM STORAGECLASS REASON AGE -pvc-80bde37a-3c5b-40f4-87f3-8440e658be75 64Gi RWO Delete Bound camunda/elasticsearch-master-elasticsearch-master-0 standard 20d -pvc-3e9129bc-9415-46c3-a005-00ce3b9b3be9 64Gi RWO Delete Bound camunda/elasticsearch-master-elasticsearch-master-1 standard 20d +helm upgrade camunda ``` -The final step here is to change Persistent Volumes reclaim policy: - -```shell -kubectl patch persistentvolume "${ES_PV_NAME0}" \ - -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}' - -kubectl patch persistentvolume "${ES_PV_NAME1}" \ - -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}' -``` +## Upgrade failed -#### 2. Update Elasticsearch PersistentVolumeClaim labels +The following upgrade error is related to [secrets extraction](#extract-secrets): ```shell -kubectl label persistentvolumeclaim elasticsearch-master-elasticsearch-master-0 \ - release=camunda chart=elasticsearch app=elasticsearch-master - -kubectl label persistentvolumeclaim elasticsearch-master-elasticsearch-master-1 \ - release=camunda chart=elasticsearch app=elasticsearch-master -``` - -#### 3. Delete Elasticsearch StatefulSet +Error: UPGRADE FAILED: execution error at (camunda-platform/charts/identity/templates/tasklist-secret.yaml:10:22): +PASSWORDS ERROR: You must provide your current passwords when upgrading the release. + Note that even after reinstallation, old credentials may be needed as they may be kept in persistent volume claims. + Further information can be obtained at https://docs.bitnami.com/general/how-to/troubleshoot-helm-chart-issues/#credential-errors-while-upgrading-chart-releases -Note that there will be a **downtime** between this step and the next step. + 'global.identity.auth.tasklist.existingSecret' must not be empty, please add '--set global.identity.auth.tasklist.existingSecret=$TASKLIST_SECRET' to the command. To get the current value: -```shell -kubectl delete statefulset elasticsearch-master + export TASKLIST_SECRET=$(kubectl get secret --namespace "camunda" "camunda-platform-test-tasklist-identity-secret" -o jsonpath="{.data.tasklist-secret}" | base64 --decode) ``` -#### 4. Apply Elasticsearch StatefulSet chart - -```shell -helm template camunda/camunda-platform camunda --version \ - --show-only charts/elasticsearch/templates/statefulset.yaml -``` +When the Helm chart is removed or upgraded, persistent volume claims (PVCs) for secret storage are not removed nor recreated. To prevent Helm from recreating secrets that have already been generated, the [Bitnami](https://github.com/bitnami/charts/tree/master/bitnami/common) library chart used by Camunda blocks the upgrade path, resulting in the above error. -The `CHART_VERSION` is the version you want to update to (`8.0.13` or later). +To complete your upgrade, [extract your secrets](#extract-secrets), then provide them as environment variables during the upgrade process. diff --git a/versioned_docs/version-8.5/self-managed/setup/upgrade.md b/versioned_docs/version-8.5/self-managed/setup/upgrade.md index da78227094..3b3dddf838 100644 --- a/versioned_docs/version-8.5/self-managed/setup/upgrade.md +++ b/versioned_docs/version-8.5/self-managed/setup/upgrade.md @@ -2,122 +2,53 @@ id: upgrade title: "Camunda 8 Helm upgrade" sidebar_label: "Upgrade" -description: "To upgrade to a more recent version of the Camunda Helm charts, there are certain things you need to keep in mind." +description: "Upgrade to a more recent version of the Camunda Helm charts, and view configuration changes between versions." --- -To upgrade to a more recent version of the Camunda Helm charts, configuration adjustments may be required. Review the [instructions for specific versions](#version-update-instructions) prior to starting an upgrade. +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; :::note -The recommended Helm upgrade path is to the **latest patch** release of the **next major version**. +When upgrading to a new version of the Camunda 8 Helm charts, we recommend updating to the **latest patch** release of the **next major version**. ::: -### Upgrading where Identity disabled +Upgrading between minor versions of the Camunda Helm chart may require [configuration changes](#update-your-configuration). To upgrade between patch versions or when no configuration changes are required, see the [`helm upgrade`](#identity-disabled) instructions. -Normally for a Helm upgrade, you run the [Helm upgrade](https://helm.sh/docs/helm/helm_upgrade/) command. If you have disabled Camunda Identity and the related authentication mechanism, you should be able to do an upgrade as follows: +## Upgrade requirements -```shell -helm upgrade camunda -``` - -However, if Camunda Identity is enabled (which is the default), the upgrade path is a bit more complex than just running `helm upgrade`. Read the next section to familiarize yourself with the upgrade process. - -### Upgrading where Identity enabled - -If you have installed the Camunda 8 Helm charts before with default values, this means Identity and the related authentication mechanism are enabled. For authentication, the Helm charts generate the secrets randomly if not specified on installation for each web application. If you run `helm upgrade` to upgrade to a newer chart version, you likely will see the following return: - -```shell -helm upgrade camunda-platform-test camunda/camunda-platform -``` - -You likely will see the following error: - -```shell -Error: UPGRADE FAILED: execution error at (camunda-platform/charts/identity/templates/tasklist-secret.yaml:10:22): -PASSWORDS ERROR: You must provide your current passwords when upgrading the release. - Note that even after reinstallation, old credentials may be needed as they may be kept in persistent volume claims. - Further information can be obtained at https://docs.bitnami.com/general/how-to/troubleshoot-helm-chart-issues/#credential-errors-while-upgrading-chart-releases - - 'global.identity.auth.tasklist.existingSecret' must not be empty, please add '--set global.identity.auth.tasklist.existingSecret=$TASKLIST_SECRET' to the command. To get the current value: - - export TASKLIST_SECRET=$(kubectl get secret --namespace "camunda" "camunda-platform-test-tasklist-identity-secret" -o jsonpath="{.data.tasklist-secret}" | base64 --decode) -``` - -As mentioned, this output returns because secrets are randomly generated with the first Helm installation by default if not further specified. We use a library chart [provided by Bitnami](https://github.com/bitnami/charts/tree/master/bitnami/common) for this. The generated secrets persist on persistent volume claims (PVCs), which are not maintained by Helm. - -If you remove the Helm chart release or do an upgrade, PVCs are not removed nor recreated. On an upgrade, secrets can be recreated by Helm and could lead to the regeneration of the secret values. This would mean that newly generated secrets would no longer match with the persistent secrets. To avoid such an issue, Bitnami blocks the upgrade path and prints the help message as shown above. - -In the error message, Bitnami links to their [troubleshooting guide](https://docs.bitnami.com/general/how-to/troubleshoot-helm-chart-issues/#credential-errors-while-upgrading-chart-releases). However, to avoid confusion, we will step through the troubleshooting process in this guide as well. - -### Secrets extraction +For a smooth upgrade experience, we recommend determining both your **Helm chart** and **Helm CLI** versions prior to starting your upgrade. -For a successful upgrade, you first need to extract all secrets that were previously generated. +### Helm chart version -:::note - -The following is meant as a sample script to build upon. Be sure to adapt the following script to your specific configuration. For example, when using an Identity provider other than Keycloak, the Keycloak-related secrets listed are unnecessary. It will likely be necessary to change this script to account for the secrets found in your specific environment. +As of the Camunda 8.4 release, the Camunda 8 **Helm chart** version is independent from the application version (for example, the Camunda 8.4 release uses the Helm chart version 9.0.0). The Helm chart is updated with each application release. -::: +Review the Camunda 8 Helm chart [version matrix](https://helm.camunda.io/camunda-platform/version-matrix/) to determine the application and Helm chart versions of your installation. -To extract the secrets, use the following code snippet. Make sure to replace `camunda` with your actual Helm release name. +You can also view all chart versions and application versions via the Helm CLI: ```shell -# Uncomment if Console is enabled. -# export CONSOLE_SECRET=$(kubectl get secret "camunda-console-identity-secret" -o jsonpath="{.data.console-secret}" | base64 --decode) -export TASKLIST_SECRET=$(kubectl get secret "camunda-tasklist-identity-secret" -o jsonpath="{.data.tasklist-secret}" | base64 --decode) -export OPTIMIZE_SECRET=$(kubectl get secret "camunda-optimize-identity-secret" -o jsonpath="{.data.optimize-secret}" | base64 --decode) -export OPERATE_SECRET=$(kubectl get secret "camunda-operate-identity-secret" -o jsonpath="{.data.operate-secret}" | base64 --decode) -export CONNECTORS_SECRET=$(kubectl get secret "camunda-connectors-identity-secret" -o jsonpath="{.data.connectors-secret}" | base64 --decode) -export ZEEBE_SECRET=$(kubectl get secret "camunda-zeebe-identity-secret" -o jsonpath="{.data.zeebe-secret}" | base64 --decode) -export KEYCLOAK_ADMIN_SECRET=$(kubectl get secret "camunda-keycloak" -o jsonpath="{.data.admin-password}" | base64 --decode) -export KEYCLOAK_MANAGEMENT_SECRET=$(kubectl get secret "camunda-keycloak" -o jsonpath="{.data.management-password}" | base64 --decode) -export POSTGRESQL_SECRET=$(kubectl get secret "camunda-postgresql" -o jsonpath="{.data.postgres-password}" | base64 --decode) -``` - -After exporting all secrets into environment variables, run the following upgrade command: - -```shell -helm upgrade camunda camunda/camunda-platform \ - # Uncomment if Console is enabled. - # --set global.identity.auth.console.existingSecret=$CONSOLE_SECRET \ - --set global.identity.auth.tasklist.existingSecret=$TASKLIST_SECRET \ - --set global.identity.auth.optimize.existingSecret=$OPTIMIZE_SECRET \ - --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 identityKeycloak.auth.adminPassword=$KEYCLOAK_ADMIN_SECRET \ - --set identityKeycloak.auth.managementPassword=$KEYCLOAK_MANAGEMENT_SECRET \ - --set identityKeycloak.postgresql.auth.password=$POSTGRESQL_SECRET +helm search repo camunda/camunda-platform --versions ``` -:::note +### Helm CLI version -If you have specified on the first installation certain values, you have to specify them again on the upgrade either via `--set` or the values file and the `-f` flag. +Use the recommended Helm CLI version for your Helm chart when upgrading. The Helm CLI version for each chart can be found on the [chart version matrix](https://helm.camunda.io/camunda-platform/version-matrix/). -::: +## Update your configuration -For more details on the Keycloak upgrade path, you can also read the [Keycloak Upgrading Guide](https://www.keycloak.org/docs/latest/upgrading/). +Configuration adjustments may be required when upgrading to a new version of the Helm chart. Before beginning your upgrade, ensure you have implemented any changes required by your new version. -## Version update instructions + -As of the 8.4 release, the Camunda 8 **Helm chart** version is decoupled from the version of the application. The Helm chart release still follows the applications release cycle, but it has an independent version. (e.g., in the application release cycle 8.4, the chart version is 9.0.0). + -For more details about the applications version included in the Helm chart, review the [full version matrix](https://helm.camunda.io/camunda-platform/version-matrix/). - -You can also view all chart versions and application versions via Helm CLI as follows: - -```shell -helm search repo camunda/camunda-platform --versions -``` - -**After applying the instructions for each Helm chart, get back to the top of this page and start the upgrade process. ** - -## Helm CLI version - -For a smooth upgrade, always use the same Helm CLI version corresponding with the chart version that shows in the [chart version matrix](https://helm.camunda.io/camunda-platform/version-matrix/). - -## From Camunda 8.4 to 8.5 - -### Helm chart 10.2.0+ +

Helm chart 10.2.0+

As of this Helm chart version, the image tags for all components are independent, and do not reference the global image tag. The value of the key `global.image.tag` is `null`, and each component now sets its own version. @@ -125,7 +56,7 @@ With this change, Camunda applications no longer require a unified patch version The key `global.image.tag` is deprecated and it will be removed in the Camunda 8.6 release. -### Helm chart 10.0.2+ +

Helm chart 10.0.2+

The upgrade path for Camunda Helm Chart v9.x.x is v10.0.2+. @@ -246,9 +177,11 @@ In v10.0.0, it is possible to use external Elasticsearch. For more information o In v10.0.0, it is possible to use external OpenSearch. For more information on how to set up external OpenSearch, refer to [using external OpenSearch](./guides/using-existing-opensearch.md). -## From Camunda 8.3 to 8.4 + + + -### Helm Chart 9.3.0 +

Helm Chart 9.3.0

#### Enabling Console @@ -270,7 +203,7 @@ To add the Console role: You should now be able to log into Console. -### Helm Chart 9.0.0 +

Helm Chart 9.0.0

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). @@ -300,9 +233,11 @@ The embedded Keycloak Helm chart has been upgraded from 16.1.7 to 17.3.6 (only t Elasticsearch image has been upgraded from 8.8.2 to 8.9.2. -## From Camunda 8.2 to 8.3 + -### Helm Chart 8.3.1 + + +

Helm Chart 8.3.1

:::caution The following steps are applied when upgrading from **any** previous version, including `8.3.0`. @@ -331,7 +266,7 @@ The following resources have been renamed: - **ConfigMap:** From `camunda-zeebe-gateway-gateway` to `camunda-zeebe-gateway`. - **ServiceAccount:** From `camunda-zeebe-gateway-gateway` to `camunda-zeebe-gateway`. -### Helm Chart 8.3.0 (minor) +

Helm Chart 8.3.0 (minor)

:::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. @@ -561,230 +496,82 @@ webModeler: url: "jdbc:postgresql://web-modeler-postgres-ext:5432/rest-api-db" ``` -## From Camunda 8.1 to 8.2 - -### Helm Chart 8.2.9 - -#### 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: + -| Optimize version | Camunda Helm chart version | -| --------------------------------- | -------------------------- | -| Optimize 3.10.1 & Optimize 3.10.2 | 8.2.0 - 8.2.8 | -| Optimize 3.10.3 | 8.2.9+ | +## Upgrade Camunda -No action is needed if you use Optimize 3.10.3 (shipped with this Helm chart version by default), but this Optimize version cannot be used out of the box with previous Helm chart versions. +If you have installed the Camunda 8 Helm charts before with default values, Identity and the related authentication mechanism are enabled. If you have disabled Identity, see how to upgrade Camunda [with Identity disabled](#identity-disabled). -### Helm Chart 8.2.3 +### Identity enabled -#### Zeebe Gateway - -:::caution Breaking change +#### Extract secrets -Zeebe Gateway authentication is now enabled by default. +If not specified on installation, the Helm chart generates random secrets for all components (including Keycloak). To upgrade successfully, these secrets must be extracted and provided during your upgrade. -::: - -To authenticate: - -1. [Create a client credential](/guides/setup-client-connection-credentials.md). -2. [Assign permissions to the application](/self-managed/identity/user-guide/authorizations/managing-resource-authorizations.md). -3. Connect with: - -- [Desktop Modeler](/components/modeler/desktop-modeler/connect-to-camunda-8.md). -- [Zeebe client (zbctl)](/self-managed/zeebe-deployment/security/secure-client-communication.md#zbctl). - -### Helm Chart 8.2.0 (Minor) - -#### Connectors - -Camunda 8 Connectors component is one of our applications which performs the integration with an external system. - -Currently, in all cases, either you will use Connectors v8.2 or not, this step should be done. You need to create the Connectors secret object (more details about this in [camunda-platform-helm/656](https://github.com/camunda/camunda-platform-helm/issues/656)). - -First, generate the Connectors secret: - -```shell -helm template camunda camunda/camunda-platform --version 8.2 \ - --show-only charts/identity/templates/connectors-secret.yaml > - identity-connectors-secret.yaml -``` - -Then apply it: +To extract the secrets, use the following code snippet, replacing `camunda` with your actual Helm release name: ```shell -kubectl apply --namespace -f identity-connectors-secret.yaml -``` - -#### Keycloak - -Camunda v8.2 uses Keycloak v19 which depends on PostgreSQL v15. That is a major change for the dependencies. Currently there are two recommended options to upgrade from Camunda 8.1.x to 8.2.x: - -1. Use the previous version of PostgreSQL v14 in Camunda v8.2, this should be simple and it will work seamlessly. -2. Follow the official PostgreSQL upgrade guide: [Upgrading a PostgreSQL Cluster v15](https://www.postgresql.org/docs/15/upgrading.html). However, it requires some manual work and longer downtime to do the database schema upgrade. - -**Method 1: Use the previous version PostgreSQL v14** - -You can set the PostgreSQL image tag as follows: - -```yaml -identity: - keycloak: - postgresql: - image: - tag: 14.5.0 -``` - -Then follow the [typical upgrade steps](#upgrading-where-identity-enabled). - -**Method 2: Upgrade the database schema to work with PostgreSQL v15** - -The easiest way to upgrade major versions of postgresql is to start a port-forward, -and then run `pg_dump` or `pg_restore`. The postgresql client versions are fairly flexible -with different server versions, but for best results, we recommend using the newest -client version. - -1. In one terminal, start a `port-forward` against the postgresql service: - -```shell -kubectl port-forward svc/camunda-postgresql 5432 -``` - -Follow the rest of these steps in a different terminal. - -2. Get the 'postgres' users password from the postgresql service: - -```shell -kubectl exec -it statefulset/camunda-postgresql -- env | grep "POSTGRES_POSTGRES_PASSWORD=" -``` - -3. Scale identity down using the following command: - -```shell -kubectl scale --replicas=0 deployment camunda-identity -``` - -4. Perform the database dump: - -```shell -pg_dumpall -U postgres -h localhost -p 5432 | tee dump.psql -Password: -``` - -`pg_dumpall` may ask multiple times for the same password. The database will be dumped into `dump.psql`. - -5. Scale database down using the following command: - -```shell -kubectl scale --replicas=0 statefulset camunda-postgresql -``` - -6. Delete the PVC for the postgresql instance using the following command: - -```shell -kubectl delete pvc data-camunda-postgresql-0 -``` - -7. Update the postgresql version using the following command: - -```shell -kubectl set image statefulset/camunda-postgresql postgresql=docker.io/bitnami/postgresql:15.3.0 -``` - -8. Scale the services back up using the following command: - -```shell -kubectl scale --replicas=1 statefulset camunda-postgresql -``` - -9. Restore the database dump using the following command: - -```shell -psql -U postgres -h localhost -p 5432 -f dump.psql -``` - -10. Scale up identity using the following command: - -```shell -kubectl scale --replicas=1 deployment camunda-identity +# Uncomment if Console is enabled. +# export CONSOLE_SECRET=$(kubectl get secret "camunda-console-identity-secret" -o jsonpath="{.data.console-secret}" | base64 --decode) +export TASKLIST_SECRET=$(kubectl get secret "camunda-tasklist-identity-secret" -o jsonpath="{.data.tasklist-secret}" | base64 --decode) +export OPTIMIZE_SECRET=$(kubectl get secret "camunda-optimize-identity-secret" -o jsonpath="{.data.optimize-secret}" | base64 --decode) +export OPERATE_SECRET=$(kubectl get secret "camunda-operate-identity-secret" -o jsonpath="{.data.operate-secret}" | base64 --decode) +export CONNECTORS_SECRET=$(kubectl get secret "camunda-connectors-identity-secret" -o jsonpath="{.data.connectors-secret}" | base64 --decode) +export ZEEBE_SECRET=$(kubectl get secret "camunda-zeebe-identity-secret" -o jsonpath="{.data.zeebe-secret}" | base64 --decode) +export KEYCLOAK_ADMIN_SECRET=$(kubectl get secret "camunda-keycloak" -o jsonpath="{.data.admin-password}" | base64 --decode) +export KEYCLOAK_MANAGEMENT_SECRET=$(kubectl get secret "camunda-keycloak" -o jsonpath="{.data.management-password}" | base64 --decode) +export POSTGRESQL_SECRET=$(kubectl get secret "camunda-postgresql" -o jsonpath="{.data.postgres-password}" | base64 --decode) ``` -Then follow the [typical upgrade steps](#upgrading-where-identity-enabled). - -## From Camunda 8.0 to 8.1 - -No Helm chart upgrade instructions for this version. +#### Run `helm upgrade` -## From Camunda 1.3 to 8.0 - -### Helm Chart 8.0.13 - -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: +After exporting all secrets into environment variables, run the following upgrade command: ```shell -helm repo add elastic https://helm.elastic.co +helm upgrade camunda camunda/camunda-platform \ + # Uncomment if Console is enabled. + # --set global.identity.auth.console.existingSecret=$CONSOLE_SECRET \ + --set global.identity.auth.tasklist.existingSecret=$TASKLIST_SECRET \ + --set global.identity.auth.optimize.existingSecret=$OPTIMIZE_SECRET \ + --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 identityKeycloak.auth.adminPassword=$KEYCLOAK_ADMIN_SECRET \ + --set identityKeycloak.auth.managementPassword=$KEYCLOAK_MANAGEMENT_SECRET \ + --set identityKeycloak.postgresql.auth.password=$POSTGRESQL_SECRET ``` -#### 1. Retain Elasticsearch Persistent Volume +If you have set secret values on installation, you must specify them again on the upgrade either via `--set`, as demonstrated above, or by passing in a values file using the `-f` flag. -First, get the name of Elasticsearch Persistent Volumes: - -```shell -ES_PV_NAME0=$(kubectl get pvc elasticsearch-master-elasticsearch-master-0 -o jsonpath="{.spec.volumeName}") +:::note +For more details on the Keycloak upgrade path, see the [Keycloak upgrade guide](https://www.keycloak.org/docs/latest/upgrading/). +::: -ES_PV_NAME1=$(kubectl get pvc elasticsearch-master-elasticsearch-master-1 -o jsonpath="{.spec.volumeName}") -``` +### Identity disabled -Make sure these are the correct Persistent Volumes: +If you have **disabled** Camunda Identity and the related authentication mechanism, Camunda can be upgraded with the following command: ```shell -kubectl get persistentvolume $ES_PV_NAME0 $ES_PV_NAME1 -``` - -It should show something like the following (note the name of the claim, it's for Elasticsearch): - -``` -NAME CAPACITY ACCESS MODES RECLAIM POLICY STATUS CLAIM STORAGECLASS REASON AGE -pvc-80bde37a-3c5b-40f4-87f3-8440e658be75 64Gi RWO Delete Bound camunda/elasticsearch-master-elasticsearch-master-0 standard 20d -pvc-3e9129bc-9415-46c3-a005-00ce3b9b3be9 64Gi RWO Delete Bound camunda/elasticsearch-master-elasticsearch-master-1 standard 20d +helm upgrade camunda ``` -The final step here is to change Persistent Volumes reclaim policy: - -```shell -kubectl patch persistentvolume "${ES_PV_NAME0}" \ - -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}' - -kubectl patch persistentvolume "${ES_PV_NAME1}" \ - -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}' -``` +## Upgrade failed -#### 2. Update Elasticsearch PersistentVolumeClaim labels +The following upgrade error is related to [secrets extraction](#extract-secrets): ```shell -kubectl label persistentvolumeclaim elasticsearch-master-elasticsearch-master-0 \ - release=camunda chart=elasticsearch app=elasticsearch-master - -kubectl label persistentvolumeclaim elasticsearch-master-elasticsearch-master-1 \ - release=camunda chart=elasticsearch app=elasticsearch-master -``` - -#### 3. Delete Elasticsearch StatefulSet +Error: UPGRADE FAILED: execution error at (camunda-platform/charts/identity/templates/tasklist-secret.yaml:10:22): +PASSWORDS ERROR: You must provide your current passwords when upgrading the release. + Note that even after reinstallation, old credentials may be needed as they may be kept in persistent volume claims. + Further information can be obtained at https://docs.bitnami.com/general/how-to/troubleshoot-helm-chart-issues/#credential-errors-while-upgrading-chart-releases -Note that there will be a **downtime** between this step and the next step. + 'global.identity.auth.tasklist.existingSecret' must not be empty, please add '--set global.identity.auth.tasklist.existingSecret=$TASKLIST_SECRET' to the command. To get the current value: -```shell -kubectl delete statefulset elasticsearch-master + export TASKLIST_SECRET=$(kubectl get secret --namespace "camunda" "camunda-platform-test-tasklist-identity-secret" -o jsonpath="{.data.tasklist-secret}" | base64 --decode) ``` -#### 4. Apply Elasticsearch StatefulSet chart - -```shell -helm template camunda/camunda-platform camunda --version \ - --show-only charts/elasticsearch/templates/statefulset.yaml -``` +When the Helm chart is removed or upgraded, persistent volume claims (PVCs) for secret storage are not removed nor recreated. To prevent Helm from recreating secrets that have already been generated, the [Bitnami](https://github.com/bitnami/charts/tree/master/bitnami/common) library chart used by Camunda blocks the upgrade path, resulting in the above error. -The `CHART_VERSION` is the version you want to update to (`8.0.13` or later). +To complete your upgrade, [extract your secrets](#extract-secrets), then provide them as environment variables during the upgrade process.