wbsong111
611e971295
codecentric/keycloak(18.4.0, WildFly 기반, appVersion 17.0.1-legacy)이 bitnami/postgresql 서브차트를 조건부 의존성으로 포함해 bitnami 무료 배포 정책 변경 문제가 그대로 전이됐다. codecentric은 이 WildFly 차트를 더 이상 갱신하지 않고 Quarkus 기반 Keycloak(17+)용 별도 차트 keycloakx를 제공하며, keycloakx는 서브차트 의존성이 전혀 없어(Chart.yaml에 dependencies 없음) 문제가 근본적으로 해소된다. 실제 소비자가 없어(문서 예시 표 한 줄 외 참조 없음) phased 전환 없이 keycloak/18.4.0을 같은 커밋에서 제거했다. custom-values.yaml 작성 시 확인한 핵심 사항 — 이 차트의 http.relativePath 기본값이 구버전 WildFly Keycloak 호환용 "/auth"라, 명시적으로 "/"로 오버라이드해야 한다(안 하면 OIDC issuer/admin API 경로가 소비 앱들의 경로 접미사 없음 가정과 어긋난다). database.existingSecret/existingSecretKey 로 kubernetes.io/basic-auth 시크릿을 그대로 참조 가능함도 helm template로 확인했다. Closes #1 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
118 lines
3.9 KiB
Markdown
118 lines
3.9 KiB
Markdown
# keycloakx 배포
|
|
|
|
## 1. 배포 방법
|
|
|
|
### 1) 배포 시 주의 사항
|
|
|
|
- keycloakx를 배포하려면 외부 postgresql이 필요하다(이 차트는 내장 DB를 지원하지 않는다 — 서브차트 의존성 없음).
|
|
- `custom-values.yaml`의 `database.*` 를 배포된 DB 정보로 변경한다.
|
|
- **`http.relativePath: "/"` 를 지우거나 값을 바꾸지 말 것.** 이 차트의 기본값은 구버전 WildFly Keycloak 호환을 위한 `"/auth"`다. `"/"`로 명시하지 않으면 Quarkus 네이티브 경로 규칙과 달라져, OIDC issuer URL(`/realms/{realm}`)이나 admin REST API(`/admin/realms/...`)를 경로 접미사 없이 호출하는 소비 앱들의 연동이 조용히 깨진다.
|
|
|
|
### 2) 배포 방법
|
|
|
|
``` sh
|
|
git clone https://github.com/paasup/dip-catalog.git
|
|
cd manifests/helm/keycloakx/7.2.2
|
|
helm upgrade keycloak ./ -f custom-values.yaml --install -n platform --create-namespace
|
|
```
|
|
|
|
## 2. custom-values.yaml 설명
|
|
|
|
### 1) pod 설정
|
|
|
|
| Name | 설명 | 기본값 |
|
|
| --- | --- | --- |
|
|
| `image.repository`/`image.tag` | 오프라인 설치 시에는 사설 미러 레지스트리로 변경. | `quay.io/keycloak/keycloak:26.6.4` |
|
|
| `resources` | keycloak pod의 자원 설정. | `custom-values.yaml 참조` |
|
|
|
|
### 2) Postgresql 연동 설정
|
|
|
|
`database.*` 구조화 필드를 사용한다(구버전 `keycloak` 차트의 `DB_VENDOR`/`DB_ADDR` 같은 extraEnv 방식이 아니다).
|
|
|
|
``` yaml
|
|
database:
|
|
vendor: postgres
|
|
hostname: keycloak-postgresql # 배포된 DB 서비스명으로 변경
|
|
port: 5432
|
|
database: keycloak
|
|
username: keycloak
|
|
existingSecret: keycloak-db # kubernetes.io/basic-auth 시크릿 이름
|
|
existingSecretKey: password # 시크릿 안의 비밀번호 키 (기본값 "password")
|
|
|
|
extraEnv: |
|
|
- name: KC_DB_SCHEMA # public 이 아닌 전용 스키마를 쓸 때 지정
|
|
value: keycloak
|
|
- name: KC_BOOTSTRAP_ADMIN_USERNAME
|
|
value: admin
|
|
- name: KC_BOOTSTRAP_ADMIN_PASSWORD
|
|
value: Paasadm1234!
|
|
- name: TZ
|
|
value: Asia/Seoul
|
|
```
|
|
|
|
- `existingSecret`으로 지정한 시크릿은 미리 생성해야 한다(이 차트는 시크릿을 만들어주지 않고 참조만 한다):
|
|
``` sh
|
|
kubectl create secret generic keycloak-db \
|
|
--type=kubernetes.io/basic-auth \
|
|
--from-literal=username=keycloak \
|
|
--from-literal=password=<비밀번호> \
|
|
-n platform
|
|
```
|
|
- `KC_BOOTSTRAP_ADMIN_USERNAME`/`KC_BOOTSTRAP_ADMIN_PASSWORD`(Keycloak 25+ 표준 부트스트랩 메커니즘)는 **master realm이 완전히 비어있는 최초 부팅에만** admin 계정을 생성한다. 재설치·재기동 시 비밀번호를 바꿔주지 않는다 — 정상 동작이다.
|
|
|
|
### 3) Ingress 설정
|
|
|
|
#### 3.1) tls 시크릿 직접 생성
|
|
|
|
``` yaml
|
|
ingress:
|
|
enabled: true
|
|
ingressClassName: apisix # 사용하는 ingress controller 클래스로 변경
|
|
rules:
|
|
- host: keycloak.example.org # keycloak에서 사용할 도메인으로 변경
|
|
paths:
|
|
- path: /
|
|
pathType: Prefix
|
|
tls:
|
|
- hosts:
|
|
- keycloak.example.org # keycloak에서 사용할 도메인으로 변경
|
|
secretName: keycloak-tls
|
|
```
|
|
|
|
인증서를 secret으로 직접 제공하는 경우:
|
|
|
|
``` sh
|
|
kubectl create secret tls keycloak-tls --cert=<path-to-cert-file> --key=<path-to-key-file> -n <namespace>
|
|
```
|
|
|
|
#### 3.2) cert-manager를 이용한 자동 생성
|
|
|
|
`custom-values.yaml`의 `ingress.annotations.cert-manager.io/cluster-issuer`를 미리 배포된 ClusterIssuer 이름으로 변경한다.
|
|
|
|
``` yaml
|
|
ingress:
|
|
enabled: true
|
|
ingressClassName: apisix
|
|
annotations:
|
|
cert-manager.io/cluster-issuer: "root-ca-issuer"
|
|
rules:
|
|
- host: keycloak.example.org
|
|
paths:
|
|
- path: /
|
|
pathType: Prefix
|
|
tls:
|
|
- hosts:
|
|
- keycloak.example.org
|
|
secretName: keycloak-tls
|
|
```
|
|
|
|
### 4) Proxy 설정
|
|
|
|
ingress/리버스 프록시 뒤에 배포하는 표준 구성:
|
|
|
|
``` yaml
|
|
proxy:
|
|
enabled: true
|
|
mode: forwarded
|
|
```
|