service-catalog/manifests/helm/keycloakx/7.2.2/CUSTOM-README.md

# 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/...`)를 경로 접미사 없이 호출하는 소비 앱들의 연동이 조용히 깨진다.
- **`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) 배포 방법

``` 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_HOSTNAME              # 필수 — 미지정 시 hostname-strict 검증으로 기동 실패
    value: keycloak.example.org
  - 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
```