wbsong111
e1e3926430
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 <noreply@anthropic.com>
89 lines
3.9 KiB
Markdown
89 lines
3.9 KiB
Markdown
# keycloakx 버전 갱신 가이드
|
|
|
|
## 1. git 작업 환경 구성
|
|
|
|
- DIP 카탈로그 git 다운로드
|
|
```
|
|
$ git clone https://github.com/paasup/dip-catalog.git
|
|
```
|
|
|
|
- 작업 브랜치로 체크아웃
|
|
```
|
|
$ git checkout -b update-keycloakx/7.2.2
|
|
```
|
|
|
|
## 2. helm chart 업데이트
|
|
|
|
#### * 배경 — 왜 keycloakx인가 (이슈 #1)
|
|
|
|
기존 `manifests/helm/keycloak/` 는 codecentric의 구버전 WildFly 기반 `keycloak` 차트(17.0.1-legacy)였고, bitnami postgresql 서브차트를 조건부 의존성으로 포함하고 있었다(bitnami 무료 배포 정책 변경으로 문제가 된 지점). codecentric은 17.0.1 이후 이 WildFly 차트를 더 이상 업데이트하지 않고, Quarkus 기반 Keycloak(17+)용으로 새 차트 `keycloakx`를 별도로 제공한다. `keycloakx`는 서브차트 의존성이 전혀 없어(`Chart.yaml`에 dependencies 없음) bitnami 의존 문제가 근본적으로 해소된다 — 그래서 `keycloak` 대신 `keycloakx`로 신규 등록한다. 기존 `manifests/helm/keycloak/18.4.0/` 는 같은 PR에서 제거한다(실제 소비자 없음, 문서 예시 표 한 줄 외 참조 없음).
|
|
|
|
### 1) 차트 버전 변경
|
|
|
|
- BUILD-README.md, CUSTOM-README.md, custom-values.yaml을 제외한 파일 삭제.
|
|
``` sh
|
|
# chart 디렉토리로 이동
|
|
cd manifests/helm/keycloakx/7.2.2
|
|
|
|
# 파일 삭제 전 삭제할 파일 목록 확인
|
|
find . -mindepth 1 \( -name "CUSTOM-README.md" -o -name "BUILD-README.md" -o -name "custom-values.yaml" \) -prune -o -print
|
|
|
|
# 파일 삭제
|
|
find . -mindepth 1 \( -name "CUSTOM-README.md" -o -name "BUILD-README.md" -o -name "custom-values.yaml" \) -prune -o -exec rm -rf {} +
|
|
```
|
|
|
|
- codecentric/keycloakx 차트 다운로드
|
|
``` sh
|
|
# manifests/helm 디렉토리로 이동
|
|
cd manifests/helm
|
|
|
|
# helm repo 추가
|
|
helm repo add codecentric https://codecentric.github.io/helm-charts
|
|
helm repo update
|
|
|
|
# helm 차트 pull
|
|
helm pull codecentric/keycloakx --version="7.2.2" --untar --untardir /tmp/keycloakx-pull
|
|
|
|
# 새 버전 디렉토리로 복사
|
|
mkdir -p keycloakx/7.2.2
|
|
cp -R /tmp/keycloakx-pull/keycloakx/. keycloakx/7.2.2/
|
|
rm -rf /tmp/keycloakx-pull
|
|
```
|
|
|
|
## 3. git push 및 tag 추가
|
|
|
|
- 갱신작업 진행 후 commit
|
|
```
|
|
$ git add .
|
|
$ git commit -m "add keycloakx/7.2.2 (이슈 #1 대응, keycloak/18.4.0 대체)"
|
|
```
|
|
|
|
- main 브랜치에 체크아웃 후 merge
|
|
```
|
|
$ git checkout main
|
|
$ git merge update-keycloakx/7.2.2
|
|
```
|
|
|
|
- git에 push 후 작업 브랜치 삭제
|
|
```
|
|
$ git push -u origin main
|
|
$ git branch -d update-keycloakx/7.2.2
|
|
```
|
|
|
|
- git tag 추가 후 push
|
|
```
|
|
$ git tag keycloakx/7.2.2
|
|
$ git push origin keycloakx/7.2.2
|
|
```
|
|
|
|
## 4. 차트 버전 정보
|
|
|
|
- keycloakx/7.2.2 (appVersion 26.6.4)
|
|
- `manifests/helm/keycloak/18.4.0`(codecentric 구버전 WildFly 기반, bitnami postgresql 서브차트 포함) 대체. 신규 등록.
|
|
- 서브차트 의존성 없음(`Chart.yaml`에 dependencies 없음).
|
|
- 서비스 배포를 위하여 custom-values.yaml에 정의하였다.
|
|
- **주의 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 호출까지 성공).
|