donghyeon.kang/llm-wiki

Fork 0

Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

11 KiB

Raw Blame History

title, source_type, url, archive_url, related_branches, related_projects, tags, created

title

source_type

url

archive_url

related_branches

related_projects

official-doc / Keycloak — Tracking Instance Status with Health Checks

Layer: raw/ — 외부 자료(공식 문서)의 원문 발췌·출처 기록. 검증된 요약은 /ingest 후 wiki/concepts/에 source-summary-template 형식으로 별도 작성. 원본은 raw에 영구 보관.

Parent / 활용 branch (필수, 최소 1개+)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-keycloak-docker-compose-stack	D3 — container healthcheck 로 startup ordering 강제. Keycloak health endpoint 경로 (`/health`, `/health/ready`, `/health/live`, `/health/started`), 노출 포트(management port `9000`), 그리고 `health-enabled`/`KC_HEALTH_ENABLED` 명시적 활성화 필요성(기본값 `false`)의 공식 근거

출처 / Source

원본 URL: https://www.keycloak.org/observability/health
아카이브 URL: (미제공)
저자 / 조직: Keycloak Team (Keycloak 공식 프로젝트 문서, CNCF incubation project)
발행일: 불명 (페이지 버전 셀렉터 스냅샷 26.7.0; GitHub 소스 docs/guides/observability/health.adoc)
마지막 확인일: 2026-07-16

왜 저장했는지 / Why archived

feature-keycloak-docker-compose-stack branch 의 D3(healthcheck 기반 startup 강제) 결정에서 Keycloak 이 health endpoint 를 어떤 경로·포트로 노출하는지, 기본 비활성화 상태인지가 UNSUPPORTED_DECISION 으로 남아 있었다. 본 공식 문서는 경로·포트·활성화 방법 세 가지를 모두 직접 명시하며, 컨테이너 환경에서의 healthcheck 작성 패턴(curl 부재 시 bash TCP redirect)까지 제공한다.

핵심 인용 / Key quotes (verbatim, 3~5문장)

[Preamble] "Keycloak has built in support for health checks. This guide describes how to enable and use the Keycloak health checks. The Keycloak health checks are exposed on the management port 9000 by default. For more details, see Configuring the Management Interface" (line 2)

[§Relevant options — health-enabled row] "If enabled, health checks are available at the /health, /health/ready and /health/live endpoints." (line 91) — 관련 엔드포인트 상세: "/health/started - Startup probe used for initial startup of Keycloak before the liveness probe takes over." (line 7)

[§Relevant options — health-enabled row] "CLI: --health-enabled" (line 92) / "Env: KC_HEALTH_ENABLED" (line 93) — Type or Values 열: "true, false" (line 94) / Default 열: "false" (line 95)

[§Using the health checks] "Due to security measures that remove curl and other packages from the Keycloak container image, you are not able to run checks against HTTPS endpoints from within the container." (line 45)

[§HEALTHCHECK] "{ printf 'HEAD /health/ready HTTP/1.0\r\n\r\n' >&0; grep 'HTTP/1.0 200'; } 0<>/dev/tcp/localhost/9000" (line 59)

[§Kubernetes] "Define a HTTP Probe so that Kubernetes may externally monitor the health endpoints. Do not use a liveness command." (line 55)

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
KC-HEALTH-C1	Keycloak health check 는 기본적으로 management port `9000` 에서 노출된다 (main HTTP(S) 포트와 분리)	[line 2] "The Keycloak health checks are exposed on the management port 9000 by default."	`official-vendor-doc`	management interface 기본 설정 (`http-management-health-enabled` 를 `false` 로 바꾸지 않은 경우)	`http-management-port` 를 변경했을 때의 동작, docker-compose 네트워크 내에서 이 포트가 별도로 `ports:` 매핑되어야 하는지 여부
KC-HEALTH-C2	health check 는 `/health`, `/health/ready`, `/health/live`, `/health/started` 4개 endpoint 로 존재하며, `health-enabled` 옵션이 활성화(`enabled`)된 경우에 "available" 하다	[line 91] "If enabled, health checks are available at the /health, /health/ready and /health/live endpoints." + [line 7] "/health/started - Startup probe used for initial startup of Keycloak before the liveness probe takes over."	`official-vendor-doc`	Keycloak 26.7.0 기준, 4개 endpoint 가 동일한 `health-enabled` 플래그로 동시 활성화됨	개별 endpoint 만 선택적으로 켜는 방법; `start-dev` 학습 모드에서의 endpoint 활성화 동작 차이 (본 페이지는 build-time option 이라고만 명시, start-dev 특이사항 언급 없음)
KC-HEALTH-C3	health check 는 기본적으로 비활성화(`false`)되어 있으며, build-time CLI 플래그 `--health-enabled` 또는 환경변수 `KC_HEALTH_ENABLED` 로 명시적으로 켜야 한다 (허용값 `true`/`false`)	[line 92] "CLI: --health-enabled" / [line 93] "Env: KC_HEALTH_ENABLED" / [line 94] "true, false" / [line 95] "false" (Relevant options 표, `health-enabled` row 의 Default 열)	`official-vendor-doc`	Keycloak 26.7.0 의 공식 "Relevant options" 레퍼런스 테이블 — 이 branch 의 `KC_HEALTH_ENABLED=true` 명시 필요성 결정을 직접 뒷받침	`KC_HEALTH_ENABLED=true` 를 `start-dev` 컨테이너 기동 시 일반 환경변수로 주입하는 것만으로 충분한지 (문서 본문은 "build time option" 이라고만 서술, 별도 `kc.sh build` 단계 필요 여부는 이 페이지 범위 밖)
KC-HEALTH-C4	공식 Keycloak 컨테이너 이미지에는 `curl` 등 HTTP 클라이언트가 없어, 컨테이너 내부에서 healthcheck 를 실행하려면 bash 의 `/dev/tcp` redirect 로 raw HTTP 요청을 만들어야 한다 (Containerfile `HEALTHCHECK` 예시 제공, 대상: `/health/ready` on port `9000`)	[line 45] "Due to security measures that remove curl and other packages from the Keycloak container image, you are not able to run checks against HTTPS endpoints from within the container." + [line 59] "{ printf 'HEAD /health/ready HTTP/1.0\r\n\r\n' >&0; grep 'HTTP/1.0 200'; } 0<>/dev/tcp/localhost/9000"	`official-vendor-doc`	공식 Keycloak 컨테이너 이미지(quay.io/keycloak/keycloak) 기준 Containerfile/Docker `HEALTHCHECK` 작성 패턴 — docker-compose `healthcheck:` 블록의 `test:` 커맨드가 겨냥해야 할 endpoint+port 를 직접 뒷받침	Docker Compose `healthcheck:` YAML 문법 자체나 `depends_on: condition: service_healthy` 의 시맨틱 (Docker Compose spec 영역, 본 자료 범위 밖) — 이 문서는 어떤 endpoint/port 를 checking 해야 하는지만 근거
KC-HEALTH-C5	Kubernetes 환경에서는 exec 기반 liveness command 대신 HTTP Probe 로 health endpoint 를 외부 모니터링하도록 권고한다	[line 55] "Define a HTTP Probe so that Kubernetes may externally monitor the health endpoints. Do not use a liveness command."	`official-vendor-doc`	Kubernetes readiness/liveness probe 설계 패턴 — Keycloak 이 "in-process exec 커맨드보다 외부 HTTP 체크" 를 선호한다는 일반 원칙의 근거	Docker Compose 환경에서의 동일 권고 여부 (Kubernetes 특정 조언이며, Compose 의 container-internal exec 기반 `HEALTHCHECK` — 즉 KC-HEALTH-C4 패턴 — 과는 다른 메커니즘)

Strength 허용값

official-vendor-doc — Spring, Keycloak, AWS, Google 등 공식 벤더 문서 (본 문서 전체가 이 등급)

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- KC-HEALTH-C1: health check 가 기본적으로 management port 9000 에서 노출됨
- KC-HEALTH-C2: /health, /health/ready, /health/live, /health/started 4개 endpoint 경로가 존재함
- KC-HEALTH-C3: health check 는 기본 비활성화(false) 이며 --health-enabled / KC_HEALTH_ENABLED=true 로 명시 활성화해야 함
- KC-HEALTH-C4: 공식 이미지에 curl 이 없어 /health/ready 를 bash TCP redirect 로 조회하는 Containerfile HEALTHCHECK 패턴이 공식적으로 제시됨 — docker-compose healthcheck: test: 가 겨냥할 endpoint+port 근거로 직접 사용 가능
- KC-HEALTH-C5: Kubernetes 는 exec 커맨드 대신 HTTP Probe 를 권고함
이 자료가 증명하지 않는 것:
- Docker Compose depends_on: condition: service_healthy 의 YAML 문법·시맨틱 자체 (Docker Compose spec 영역, Keycloak 문서 범위 밖 — 별도 raw 자료 필요)
- start-dev (학습/quickstart) 모드에서 KC_HEALTH_ENABLED=true 를 일반 환경변수로 주입하는 것만으로 충분한지 (본 페이지는 health-enabled 를 "build time option" 이라고만 서술하고 start-dev 의 자동 재빌드 동작은 언급하지 않음 — 별도 확인 필요)
- Keycloak 26.x 이외 버전에서의 동일 동작 보장 (페이지 버전 셀렉터가 26.7.0 스냅샷을 가리킴)
- KC_BOOTSTRAP_ADMIN_USERNAME/KEYCLOAK_ADMIN 등 admin bootstrap 환경변수 (branch 의 별도 needs-confirmation claim — 본 자료 범위 밖)
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- docker-compose.yml 의 keycloak 서비스 healthcheck: 블록에서 공식 이미지에 실제로 curl 이 없는지 재확인 후, 없다면 이 문서의 bash /dev/tcp 패턴 채택
- docker compose up -d 후 curl http://localhost:9000/health/ready 로 실제 200 응답 확인 (management port 9000 이 compose 네트워크 내부에서 노출되는지 포함)
- start-dev 로 기동 시 KC_HEALTH_ENABLED=true 환경변수만으로 4개 endpoint 가 모두 활성화되는지 로그/curl 로 직접 검증

메모 / Notes

페이지 상단 버전 셀렉터가 Nightly / 26.7.0 두 옵션만 보여줌 — 본 발췌는 26.7.0 (기본 선택) 기준.
http-management-health-enabled 가 false 인 경우 health endpoint 는 management port 가 아니라 main HTTP(S) 포트에 남는다는 문구도 preamble 에 있음 (본 raw 에는 핵심 인용으로 포함하지 않았으나, D3 의 "포트 9000 분리" 전제가 http-management-health-enabled 기본값(true로 추정)에 의존한다는 점은 후속 확인 후보).
추가로 봐야 할 동일 출처 페이지: https://www.keycloak.org/server/management-interface (management port 분리 설정 상세, 이 페이지에서 링크됨).

raw/official-docs/keycloak-server-containers-docker — Keycloak Docker 공식 (KC_* 환경 변수, D1/D5 근거)
raw/official-docs/keycloak-getting-started-docker — Docker quickstart (D1/D6 근거)
raw/official-docs/docker-compose-depends-on-healthcheck — Docker Compose depends_on: condition: service_healthy spec 근거 (D3 의 Compose 측 절반)

11 KiB Raw Blame History