Files

T

wbsong111 9e5b6633db 자체 빌드 이미지 레포명을 security-images에서 hardened-containers로 정정한다

실제 레포명은 hardened-containers인데 이관 커밋 이후 문서·워크플로·차트 주석에
잘못된 이름 security-images가 남아 있었다. 텍스트 참조 전체를 정정하고
doc/migrations/의 이관 핸드오프 문서도 파일명까지 리네임했다. env var/secret
이름(SECURITY_IMAGES_REPO, SECURITY_IMAGES_DISPATCH_TOKEN)은 GitHub Secret
재등록이 필요한 별도 운영 작업이라 이번 텍스트 정정 범위에서 제외했다.

덧붙여 scripts/build/patch-catalog-tag.py의 docstring이 삭제된 build-image.yml을
호출자로 여전히 가리키고 있던 것도 실제 호출 경로(check-rebuild-needed.py /
apply-published-tags.py → catalog-tag-update.yml)로 고쳤다.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

2026-08-26 08:16:37 +09:00

7.1 KiB

Raw Blame History

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).
이미지는 업스트림이 아니라 자체 빌드 하드닝 이미지다 — 아래 "3. 자체 빌드 이미지" 참조. kcadm.sh/kcreg.sh(bin/client)가 들어 있지 않다.

2) 배포 방법

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`	자체 빌드 하드닝 이미지(아래 3절). 오프라인 설치 시에는 사설 미러 레지스트리로 변경.	`custom-values.yaml 참조`
`resources`	keycloak pod의 자원 설정.	`custom-values.yaml 참조`

2) Postgresql 연동 설정

database.* 구조화 필드를 사용한다(구버전 keycloak 차트의 DB_VENDOR/DB_ADDR 같은 extraEnv 방식이 아니다).

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: ChangeMe1234!        # 예시 값 — 배포 전 교체한다
  - name: TZ
    value: Asia/Seoul

existingSecret으로 지정한 시크릿은 미리 생성해야 한다(이 차트는 시크릿을 만들어주지 않고 참조만 한다):

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 시크릿 직접 생성

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으로 직접 제공하는 경우:

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 이름으로 변경한다.

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/리버스 프록시 뒤에 배포하는 표준 구성:

proxy:
  enabled: true
  mode: forwarded

3. 자체 빌드 이미지

image.repository/image.tag 는 업스트림 quay.io/keycloak/keycloak 이 아니라 docker.io/paasup/keycloak 자체 빌드 하드닝 이미지를 가리킨다. 빌드 정의와, 왜 자체 빌드인지·업스트림과 무엇이 다른지는 별도 레포 hardened-containers 의 images/keycloak/ (README.md 포함)가 단일 출처다 — 이 레포에는 없다. 배포 관점에서 알아야 할 것만 아래에 적는다.

앱 버전이 차트 `appVersion` 과 다르다

차트 appVersion 은 26.6.4 지만 이미지는 Keycloak 26.7.1 이다.

appVersion 은 image.tag 미지정 시의 기본값일 뿐이고, custom-values.yaml 이 태그를 명시하므로 실제 배포 버전은 26.7.1 이다.
codecentric keycloakx 는 7.2.2 가 최신 차트이고 아직 26.7.x 를 따라잡지 못했다 — 릴리스 캐던스 지연이지 차트 결함이 아니다.
26.6.4 를 쓰지 않는 이유: 26.7.1(및 26.6.5)에서만 패치된 keycloak-services HIGH 5건(CVE-2026-16102 / 16442 / 16443 / 15572 / 15573)에 취약하다.

업스트림 이미지와의 차이 — `kcadm.sh`/`kcreg.sh` 없음

/opt/keycloak/bin/client/ 를 제거했다. 이 디렉토리의 keycloak-admin-cli-*.jar 가 취약한 jackson 을 shade 로 품은 uber-jar 라 교체가 불가능해서다. 서버 런타임은 이 디렉토리를 쓰지 않으므로 배포 동작에는 영향이 없다.

파드에 exec 해서 kcadm.sh 를 쓰던 절차가 있다면 대안이 필요하다.

권장: admin REST API 직접 호출 (/admin/realms/..., 토큰은 /realms/master/protocol/openid-connect/token 에서 발급)
또는 업스트림 이미지(quay.io/keycloak/keycloak:26.7.1)를 일회성 잡/디버그 컨테이너로 띄워 kcadm.sh 만 쓴다 (서버로 쓰지 않는다)

이미지 갱신

hardened-containers 레포의 images/keycloak/suse.build.env 의 KEYCLOAK_VERSION 과 jar 오버레이 버전을 사람이 고쳐 커밋하는 것이 갱신 트리거다(그 레포에서). 그 레포의 build-image.yml 이 빌드·게이트 통과 후 push 하면 published.json 이 갱신되고, 이 카탈로그의 catalog-tag-update.yml 이 그것을 읽어가 이 파일의 image.tag 를 자동 갱신한 브랜치를 이 레포에 만든다.

7.1 KiB Raw Blame History