From e1e3926430729422e813556ec366a7bd50b3cd10 Mon Sep 17 00:00:00 2001 From: wbsong111 Date: Thu, 6 Aug 2026 17:34:22 +0900 Subject: [PATCH] =?UTF-8?q?add-keycloakx:=20=EC=8B=A4=EC=B8=A1=EC=9C=BC?= =?UTF-8?q?=EB=A1=9C=20=EB=B0=9C=EA=B2=AC=ED=95=9C=20command/KC=5FHOSTNAME?= =?UTF-8?q?=20=ED=95=84=EC=88=98=EA=B0=92=20=EB=B0=98=EC=98=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit dev 클러스터 격리 네임스페이스에 실제 배포해 검증하는 과정에서 두 가지 누락을 발견했다: 1. command/args 기본값이 둘 다 빈 배열이라, 지정하지 않으면 컨테이너가 인자 없는 kc.sh(도움말 출력, exit 0)로 끝나 CrashLoopBackOff가 된다. 2. hostname-strict 기본값이 true라 KC_HOSTNAME 을 지정하지 않으면 "hostname is not configured" 로 기동이 실패한다. 두 값 모두 custom-values.yaml에 추가하고, BUILD-README/CUSTOM-README에 실측 근거를 남겼다. 이후 admin 부트스트랩(KC-SERVICES0077), DB 마이그레이션, admin REST API로 realm/client 생성까지 전부 정상 동작 확인. Co-Authored-By: Claude Sonnet 5 --- manifests/helm/keycloakx/7.2.2/BUILD-README.md | 5 ++++- manifests/helm/keycloakx/7.2.2/CUSTOM-README.md | 4 ++++ manifests/helm/keycloakx/7.2.2/custom-values.yaml | 11 +++++++++++ 3 files changed, 19 insertions(+), 1 deletion(-) diff --git a/manifests/helm/keycloakx/7.2.2/BUILD-README.md b/manifests/helm/keycloakx/7.2.2/BUILD-README.md index 62d8f08..f1480c5 100644 --- a/manifests/helm/keycloakx/7.2.2/BUILD-README.md +++ b/manifests/helm/keycloakx/7.2.2/BUILD-README.md @@ -82,4 +82,7 @@ $ git push origin keycloakx/7.2.2 - `manifests/helm/keycloak/18.4.0`(codecentric 구버전 WildFly 기반, bitnami postgresql 서브차트 포함) 대체. 신규 등록. - 서브차트 의존성 없음(`Chart.yaml`에 dependencies 없음). - 서비스 배포를 위하여 custom-values.yaml에 정의하였다. - - **주의**: 이 차트의 `http.relativePath` 기본값은 `"/auth"`(구 WildFly Keycloak 호환용)다. `custom-values.yaml`에서 `"/"`로 반드시 오버라이드해야 한다 — 그대로 두면 OIDC issuer/admin API 경로가 소비자 앱들의 가정(경로 접미사 없음)과 어긋난다. + - **주의 1**: 이 차트의 `http.relativePath` 기본값은 `"/auth"`(구 WildFly Keycloak 호환용)다. `custom-values.yaml`에서 `"/"`로 반드시 오버라이드해야 한다 — 그대로 두면 OIDC issuer/admin API 경로가 소비자 앱들의 가정(경로 접미사 없음)과 어긋난다. + - **주의 2**: `command`/`args` 기본값이 둘 다 빈 배열이라, 지정하지 않으면 컨테이너가 인자 없는 `kc.sh`(도움말 출력, exit 0)로 끝나 CrashLoopBackOff가 된다. `custom-values.yaml`의 `command: ["/opt/keycloak/bin/kc.sh", "start"]`를 유지해야 한다. + - **주의 3**: `extraEnv`에 `KC_HOSTNAME`을 반드시 지정해야 한다 — 미지정 시 hostname-strict 검증(기본 true)으로 `hostname is not configured` 에러가 나며 기동이 실패한다. + - 세 항목 모두 dev 클러스터 격리 네임스페이스 실배포 테스트로 확인했다(admin 부트스트랩 로그, DB 연결, realm/client 생성 REST API 호출까지 성공). diff --git a/manifests/helm/keycloakx/7.2.2/CUSTOM-README.md b/manifests/helm/keycloakx/7.2.2/CUSTOM-README.md index 475d335..aaab8c6 100644 --- a/manifests/helm/keycloakx/7.2.2/CUSTOM-README.md +++ b/manifests/helm/keycloakx/7.2.2/CUSTOM-README.md @@ -7,6 +7,8 @@ - keycloakx를 배포하려면 외부 postgresql이 필요하다(이 차트는 내장 DB를 지원하지 않는다 — 서브차트 의존성 없음). - `custom-values.yaml`의 `database.*` 를 배포된 DB 정보로 변경한다. - **`http.relativePath: "/"` 를 지우거나 값을 바꾸지 말 것.** 이 차트의 기본값은 구버전 WildFly Keycloak 호환을 위한 `"/auth"`다. `"/"`로 명시하지 않으면 Quarkus 네이티브 경로 규칙과 달라져, OIDC issuer URL(`/realms/{realm}`)이나 admin REST API(`/admin/realms/...`)를 경로 접미사 없이 호출하는 소비 앱들의 연동이 조용히 깨진다. +- **`command`를 반드시 지정할 것.** 차트 기본값(`command: []`, `args: []`)만으로는 컨테이너가 인자 없는 `kc.sh`(도움말 출력, exit 0)로 끝나 CrashLoopBackOff가 된다(실측 확인). `custom-values.yaml`의 `command: ["/opt/keycloak/bin/kc.sh", "start"]`를 유지한다. +- **`extraEnv`에 `KC_HOSTNAME`을 반드시 지정할 것.** 미지정 시 `hostname is not configured; either configure hostname, or set hostname-strict to false`로 기동이 실패한다(실측 확인, hostname-strict 기본값 true). ### 2) 배포 방법 @@ -40,6 +42,8 @@ database: existingSecretKey: password # 시크릿 안의 비밀번호 키 (기본값 "password") extraEnv: | + - name: KC_HOSTNAME # 필수 — 미지정 시 hostname-strict 검증으로 기동 실패 + value: keycloak.example.org - name: KC_DB_SCHEMA # public 이 아닌 전용 스키마를 쓸 때 지정 value: keycloak - name: KC_BOOTSTRAP_ADMIN_USERNAME diff --git a/manifests/helm/keycloakx/7.2.2/custom-values.yaml b/manifests/helm/keycloakx/7.2.2/custom-values.yaml index b6c2b95..66bd24b 100644 --- a/manifests/helm/keycloakx/7.2.2/custom-values.yaml +++ b/manifests/helm/keycloakx/7.2.2/custom-values.yaml @@ -8,6 +8,12 @@ image: http: relativePath: "/" +# 차트 기본값은 command/args 모두 빈 배열이다 — 지정하지 않으면 컨테이너가 인자 없는 +# kc.sh(도움말 출력, exit 0)로 끝나 CrashLoopBackOff가 된다(실측 확인, dip-catalog#1). +command: + - "/opt/keycloak/bin/kc.sh" + - "start" + ingress: enabled: true ingressClassName: apisix @@ -52,7 +58,12 @@ database: # KC_BOOTSTRAP_ADMIN_USERNAME/PASSWORD: Keycloak 25+ 의 admin 계정 부트스트랩 # 메커니즘(구버전 KEYCLOAK_ADMIN/KEYCLOAK_ADMIN_PASSWORD 대체). master realm이 # 완전히 비어있는 최초 부팅에만 동작 — 재설치 시 비밀번호가 갱신되지 않는 것이 정상. +# KC_HOSTNAME: 반드시 지정할 것. hostname-strict 가 기본 true 라 미지정 시 +# "hostname is not configured; either configure hostname, or set hostname-strict +# to false" 로 기동이 실패한다(실측 확인). extraEnv: | + - name: KC_HOSTNAME + value: keycloak.example.org - name: KC_DB_SCHEMA value: keycloak - name: KC_BOOTSTRAP_ADMIN_USERNAME