Skip to content

Commit 008b8d1

Browse files
megianmegian
authored
Merge pull request #270 from projectsyn/upgrade-to-v15
Add upgrade how-to from v14 to v15
2 parents c3635e0 + 459b45c commit 008b8d1

File tree

2 files changed

+216
-0
lines changed

2 files changed

+216
-0
lines changed

‎docs/modules/ROOT/pages/how-tos/upgrade-14.x-to-15.x.adoc

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
= Upgrade from v14 to v15
2+
3+
This guide describes the steps to perform an upgrade of the component from version v14 to v15.
4+
5+
== Breaking Changes
6+
7+
* The Postgres Database will be upgraded from v11 to v15!
8+
9+
== Changes
10+
11+
* The component requires Kubernetes v1.24 or newer.
12+
* Keycloak version is v22.0.5 by default.
13+
14+
== Parameter changes
15+
16+
* `images.postgresql.tag` changed from `11.22.0-debian-11-r4` to `15.6.0-debian-12-r5`.
17+
18+
== Step-by-step guide
19+
20+
The guide helps you to create a database backup, a fresh database and a database restore.
21+
If you want to try an Postgres in-place upgrade consult this https://medium.com/@andrea.berlingieri42/upgrading-a-postgresql-bitnami-helm-release-11-to-15-2ca447b4580d[blog article].
22+
23+
When upgrading the component, the following actions are required if the built-in database is used:
24+
25+
. Export your realms within Keycloak.
26+
27+
. Disable ArgoCD sync for the Keycloak instance.
28+
+
29+
[source,bash]
30+
----
31+
# The ArgoCD app of the Keycloak instance. Change if necessary.
32+
export ARGO_APP=keycloak
33+
34+
kubectl -n syn patch applications.argoproj.io root --type=json \
35+
-p '[{"op":"replace", "path":"/spec/syncPolicy", "value": {}}]'
36+
kubectl -n syn patch applications.argoproj.io ${ARGO_APP} --type=json \
37+
-p '[{"op":"replace", "path":"/spec/syncPolicy", "value": {}}]'
38+
----
39+
40+
. Set the environment variables.
41+
+
42+
[source,bash]
43+
----
44+
# The namspace containing the Keycloak instance. Change if necessary.
45+
export NAMESPACE=syn-keycloak
46+
----
47+
48+
. Scale down the Keycloak instance.
49+
+
50+
[source,bash]
51+
----
52+
kubectl -n $NAMESPACE scale statefulset keycloakx --replicas=0
53+
54+
# Wait until statefulset has been scaled down
55+
kubectl -n $NAMESPACE get statefulset keycloakx -w
56+
----
57+
58+
. Do a backup of the built-in database.
59+
+
60+
[source,bash]
61+
----
62+
kubectl -n "${NAMESPACE}" exec -ti keycloak-postgresql-0 -c postgresql -- sh -c 'PGDATABASE="$POSTGRES_DATABASE" PGUSER="$POSTGRES_USER" PGPASSWORD="$POSTGRES_PASSWORD" pg_dump --clean' > keycloak-postgresql-$(date +%F-%H-%M-%S).sql
63+
----
64+
65+
. Scale down the Postgres database
66+
+
67+
[source,bash]
68+
----
69+
kubectl -n $NAMESPACE scale statefulset keycloak-postgresql --replicas=0
70+
71+
# Wait until statefulset has been scaled down
72+
kubectl -n $NAMESPACE get statefulset keycloak-postgresql -w
73+
----
74+
75+
. Delete the Postgres database production database persistentvolumeclaim.
76+
+
77+
[WARNING]
78+
====
79+
BEFORE GOING AHEAD ENSURE THE TAKEN BACKUP IS COMPLETE!
80+
YOU ARE GOING TO DELETE THE COMPLETE DATABASE! YOU WILL LOOSE DATA IF YOU TAKE THIS NOT CAREFULLY!
81+
82+
THE ONLY CHANCE YOU ARE NOT LOOSING ANY DATA IS YOUR BACKUP HAS BEEN COMPLETED!
83+
84+
REALLY! DO NOT PROCEED HERE WITHOUT HAVING DONE A BACKUP AND ENSURED THE DUMP CONTAINS ALL REQUIRED DATA!
85+
====
86+
+
87+
[source,bash]
88+
----
89+
kubectl -n $NAMESPACE delete persistentvolumeclaim data-keycloak-postgresql-0
90+
91+
# Wait until persistent volume claim has been deleted
92+
kubectl -n $NAMESPACE get persistentvolumeclaim data-keycloak-postgresql-0 -w
93+
----
94+
95+
. Patch the Postgres statefulset to v15.
96+
+
97+
[source,bash]
98+
----
99+
kubectl n $NAMESPACE patch sts keycloak-postgresql -p '{"spec": {"template": {"spec": {"containers": [{"name": "postgresql", "image": "docker.io/bitnami/postgresql:15.6.0-debian-12-r5"}]}}}}'
100+
----
101+
102+
. Scale up the Postgres database.
103+
+
104+
[source,bash]
105+
----
106+
kubectl -n $NAMESPACE scale statefulset keycloak-postgresql --replicas=1
107+
108+
# Wait until statefulset has been scaled up
109+
kubectl -n $NAMESPACE get statefulset keycloak-postgresql -w
110+
----
111+
112+
. Verify the Postgres database is on v15.6.
113+
+
114+
[source,bash]
115+
----
116+
kubectl -n syn-keycloak-test logs keycloak-postgresql-0 | grep "PostgreSQL 15.6"
117+
----
118+
119+
. Import the SQL dump into the Postgres v15 database.
120+
+
121+
[source,bash]
122+
----
123+
# export NAMESPACE=
124+
export POD=keycloak-postgresql-0
125+
export DUMPFILE=keycloak-postgresql-2024-02-23-13-04-21.sql
126+
127+
cat "$DUMPFILE" \
128+
| kubectl -n $NAMESPACE exec -i $POD \
129+
-- sh -c 'PGPASSWORD="${POSTGRES_PASSWORD}" psql -U "${POSTGRES_USER}" ${POSTGRES_DATABASE}'
130+
----
131+
132+
. Do a after-import backup of the built-in database.
133+
+
134+
[source,bash]
135+
----
136+
kubectl -n "${NAMESPACE}" exec -ti keycloak-postgresql-0 -c postgresql -- sh -c 'PGDATABASE="$POSTGRES_DATABASE" PGUSER="$POSTGRES_USER" PGPASSWORD="$POSTGRES_PASSWORD" pg_dump --clean' > keycloak-postgresql-$(date +%F-%H-%M-%S).sql
137+
----
138+
139+
. Compare the two files
140+
+
141+
[source,bash]
142+
----
143+
diff keycloak-postgresql-2024-02-23-13-04-21.sql keycloak-postgresql-2024-02-23-13-04-35.sql
144+
----
145+
+
146+
Should be similar to:
147+
+
148+
[source]
149+
----
150+
5,6c5,6
151+
< -- Dumped from database version 11.22
152+
< -- Dumped by pg_dump version 11.22
153+
---
154+
> -- Dumped from database version 15.6
155+
> -- Dumped by pg_dump version 15.6
156+
372a373,382
157+
> -- *not* dropping schema, since initdb creates it
158+
> --
159+
> -- Name: public; Type: SCHEMA; Schema: -; Owner: keycloak
160+
> --
161+
>
162+
> -- *not* creating schema, since initdb creates it
163+
>
164+
>
165+
> ALTER SCHEMA public OWNER TO keycloak;
166+
>
167+
375c385
168+
< SET default_with_oids = false;
169+
---
170+
> SET default_table_access_method = heap;
171+
----
172+
173+
. Scale up Keycloak
174+
+
175+
[source,bash]
176+
----
177+
kubectl -n $NAMESPACE scale sts keycloakx --replicas=2
178+
----
179+
180+
. Update the component version.
181+
+
182+
[source,bash]
183+
----
184+
parameters:
185+
components:
186+
keycloak:
187+
version: v15.0.0
188+
----
189+
190+
. (Optional) define the Postgres database container image.
191+
+
192+
[source,bash]
193+
----
194+
parameters:
195+
keycloak:
196+
images:
197+
postgresql:
198+
tag: 15.6.0-debian-12-r5
199+
----
200+
201+
. Apply the parameter changes.
202+
203+
. Compile and push the cluster catalog.
204+
205+
. Re-enable ArgoCD auto sync
206+
+
207+
[source,bash]
208+
----
209+
kubectl -n syn patch applications.argoproj.io root --type=json \
210+
-p '[{
211+
"op":"replace",
212+
"path":"/spec/syncPolicy",
213+
"value": {"automated": {"prune": true, "selfHeal": true}}
214+
}]'
215+
----

‎docs/modules/ROOT/partials/nav.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@
2626
* xref:how-tos/upgrade-11.x-to-12.x.adoc[Upgrade 11.x to 12.x]
2727
* xref:how-tos/upgrade-12.x-to-13.x.adoc[Upgrade 12.x to 13.x]
2828
* xref:how-tos/upgrade-13.x-to-14.x.adoc[Upgrade 13.x to 14.x]
29+
* xref:how-tos/upgrade-14.x-to-15.x.adoc[Upgrade 14.x to 15.x]
2930
* xref:how-tos/openshift-4.adoc[Install on OpenShift 4]
3031
* xref:how-tos/pin-versions.adoc[Pin versions]
3132

0 commit comments

Comments
 (0)