From 73a7d3c0625da1438f380ff9b04eedfdcaaec94c Mon Sep 17 00:00:00 2001
From: Gabriel Mainberger <gabriel.mainberger@vshn.net>
Date: Wed, 5 Oct 2022 14:07:27 +0200
Subject: [PATCH] Add upgrade 9.x to 10.x documentation

---
 .../pages/how-tos/upgrade-9.x-to-10.x.adoc    | 44 +++++++++++++++++++
 docs/modules/ROOT/partials/nav.adoc           |  1 +
 2 files changed, 45 insertions(+)
 create mode 100644 docs/modules/ROOT/pages/how-tos/upgrade-9.x-to-10.x.adoc

diff --git a/docs/modules/ROOT/pages/how-tos/upgrade-9.x-to-10.x.adoc b/docs/modules/ROOT/pages/how-tos/upgrade-9.x-to-10.x.adoc
new file mode 100644
index 00000000..c2c8cb33
--- /dev/null
+++ b/docs/modules/ROOT/pages/how-tos/upgrade-9.x-to-10.x.adoc
@@ -0,0 +1,44 @@
+= Upgrade from v9 to v10
+
+This guide describes the steps to perform an upgrade of the component from version v9 to v10.
+
+== Parameter changes
+
+* `charts.keycloakx` changed from `1.3.2` to `1.6.0`, the Keycloak image is updated from `17.0.2` to `18.0.2`.
+* `charts.postgresql` changed from `10.16.2` to `11.6.15`, the Postgresql version remains the same version `11.14.0-debian-10-r28`.
+* `postgresql_helm_values` authentication parameters have been moved to `postgresql_helm_values.auth` reflecting the https://docs.bitnami.com/kubernetes/infrastructure/postgresql/administration/upgrade/#to-1100[Helm chart upgrade] to 11.
+
+If you've configured custom values for any of those parameters, make sure to adjust your configurations when upgrading from component version v9 to v10.
+
+== Step-by-step guide
+
+When upgrading the component, the following actions are required if the built-in database is used:
+
+. Do a backup of the built-in database.
++
+[source,bash]
+----
+instance=keycloak
+namespace=syn-${instance}
+
+kubectl -n "${namespace}" exec -ti keycloak-postgresql-0 -c keycloak-postgresql -- sh -c 'PGDATABASE="$POSTGRES_DB" PGUSER="$POSTGRES_USER" PGPASSWORD="$POSTGRES_PASSWORD" pg_dump --clean' > keycloak-postgresql-$(date +%F-%H-%M-%S).sql
+----
+
+. Apply the parameter changes.
+
+. Compile and push the cluster catalog.
+
+. If you use the built-in database, you need to delete its StatefulSet to allow ArgoCD to apply the new version.
++
+[source,bash]
+----
+kubectl -n syn-keycloak delete sts keycloak-postgresql
+----
++
+[NOTE]
+====
+This step is necessary since the upgrade changes immutable properties in the Postgres StatefulSet if using the built-in database.
+This won't delete the PVC `data-keycloak-postgresql-0`.
+====
+
+. Verify that ArgoCD can sync all resources.
diff --git a/docs/modules/ROOT/partials/nav.adoc b/docs/modules/ROOT/partials/nav.adoc
index d3e3b273..94636295 100644
--- a/docs/modules/ROOT/partials/nav.adoc
+++ b/docs/modules/ROOT/partials/nav.adoc
@@ -21,6 +21,7 @@
 * xref:how-tos/upgrade-6.x-to-7.x.adoc[Upgrade 6.x to 7.x]
 * xref:how-tos/upgrade-7.x-to-8.x.adoc[Upgrade 7.x to 8.x]
 * xref:how-tos/upgrade-8.x-to-9.x.adoc[Upgrade 8.x to 9.x]
+* xref:how-tos/upgrade-9.x-to-10.x.adoc[Upgrade 9.x to 10.x]
 * xref:how-tos/openshift-4.adoc[Install on OpenShift 4]
 * xref:how-tos/pin-versions.adoc[Pin versions]