docs: D-2 — rolling back the image does not roll back the schema

Downgrading from 26.7.0 to 26.0 fails with liquibase ValidationFailedException on a changeset checksum, which is stricter than an unknown migration: the old version knows the changeset but its definition differs. The pod goes CrashLoopBackOff and never starts. The StatefulSet stopped the rollout at the first pod, so the other kept serving and the front door stayed at 200, which replica 1 would not have done. The failed start never touched the schema, so restoring the image was enough; had the migration already applied, the D-1 database restore would have been the only way back. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-04 15:05:36 +09:00
parent df5af95cb3
commit df140ab218
5 changed files with 275 additions and 0 deletions
@@ -0,0 +1,9 @@
+=== D-1 의 교훈: 업그레이드 전에 백업한다 ===
+  백업: 396333 bytes
+
+=== 현재 버전과 스키마 상태 ===
+quay.io/keycloak/keycloak:26.7.0
+  총 마이그레이션 수: 210
+
+=== 로그인 상태 만들기 (업그레이드 후 살아남는지 볼 것) ===
+  현재 세션: 4
@@ -0,0 +1,17 @@
+=== ★ 롤백 시도: 26.7.0 → 26.0 ===
+  시각: 15:02:20
+statefulset.apps/keycloak image updated
+  +20초  keycloak-0:Running(1/1) keycloak-1:Running(0/1) 
+  +40초  keycloak-0:Running(1/1) keycloak-1:Running(0/1) 
+  +60초  keycloak-0:Running(1/1) keycloak-1:Running(0/1) 
+  +80초  keycloak-0:Running(1/1) keycloak-1:Error(0/1) 
+  +100초  keycloak-0:Running(1/1) keycloak-1:Running(0/1) 
+  +120초  keycloak-0:Running(1/1) keycloak-1:Error(0/1) 
+  +140초  keycloak-0:Running(1/1) keycloak-1:CrashLoopBackOff(0/1) 
+  +160초  keycloak-0:Running(1/1) keycloak-1:Running(0/1) 
+
+=== 새 파드가 무엇을 말하는가 ===
+2026-09-04 06:03:25,877 ERROR [org.keycloak.quarkus.runtime.cli.ExecutionExceptionHandler] (main) ERROR: Failed to start server in (production) mode
+2026-09-04 06:03:25,877 ERROR [org.keycloak.quarkus.runtime.cli.ExecutionExceptionHandler] (main) ERROR: liquibase.exception.ValidationFailedException: Validation Failed:
+2026-09-04 06:03:25,877 ERROR [org.keycloak.quarkus.runtime.cli.ExecutionExceptionHandler] (main) ERROR: Validation Failed:
+2026-09-04 06:03:25,877 ERROR [org.keycloak.quarkus.runtime.cli.ExecutionExceptionHandler] (main) For more details run the same command passing the '--verbose' option. Also you can use '--help' to see the detai
@@ -0,0 +1,20 @@
+=== 서비스는 살아 있는가 (StatefulSet 롤링이 막아줬다) ===
+  https://auth.hyeonworks.com/realms/master  HTTP 200
+Warning: v1 Endpoints is deprecated in v1.33+; use discovery.k8s.io/v1 EndpointSlice
+  ready 주소: [10.42.1.140]sed: -e expression #1, char 27: unknown option to 's'
+
+=== Liquibase 오류 상세 ===
+2026-09-04 06:03:25,877 ERROR [org.keycloak.quarkus.runtime.cli.ExecutionExceptionHandler] (main) ERROR: liquibase.exception.ValidationFailedException: Validation Failed:
+     1 changesets check sum
+2026-09-04 06:03:25,877 ERROR [org.keycloak.quarkus.runtime.cli.ExecutionExceptionHandler] (main) ERROR: Validation Failed:
+     1 changesets check sum
+
+=== ★ 앞으로 되돌린다 (26.7.0) ===
+statefulset.apps/keycloak image updated
+partitioned roll out complete: 2 new pods have been updated...
+keycloak-0                     1/1   Running   0     10m
+keycloak-1                     1/1   Running   0     28s
+
+=== 데이터는 무사한가 ===
+  realms|clients|migrations|sessions = 2|15|210|4
+  외부 진입점 HTTP 200
@@ -0,0 +1,16 @@
+# D-2 — 버전 업그레이드 증거
+
+2026-09-04 17:05–17:15 KST
+해설: [`docs/experiment-d2-version-upgrade.md`](../../experiment-d2-version-upgrade.md)
+
+| 파일 | 무엇을 보여주는가 |
+|---|---|
+| `01-pre-upgrade.txt` | 백업 396KB · 이미지 26.7.0 · **마이그레이션 210건** · 세션 4 |
+| `02-rollback-attempt.txt` | 26.0 으로 내리자 `Running(0/1) → Error → CrashLoopBackOff`. **`liquibase.exception.ValidationFailedException`** |
+| `03-roll-forward.txt` | **서비스는 `HTTP 200` 유지**(ready 주소 1개) · 오류 원인 `1 changesets check sum` · 26.7.0 복귀 후 마이그레이션 210·세션 4 그대로 |
+
+## 핵심 세 줄
+
+1. **롤백은 안 된다.** 체크섬이 안 맞아 Liquibase 가 기동 자체를 거부한다 — "모르는 변경"이 아니라 "아는 변경인데 정의가 다르다".
+2. **StatefulSet 이 사고를 절반에서 멈춰줬다.** 한 파드가 남아 외부 200 을 유지했다. replica 1 이었다면 전면 장애다.
+3. **실패한 기동은 스키마를 안 건드렸다.** 그래서 이미지만 되돌려도 복구됐다 — 이미 적용된 뒤였다면 DB 복구(D-1)가 필요하다.