donghyeon.kang/llm-wiki

Fork 0

Files

T

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

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

9.2 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

Keycloak — Importing and exporting realms

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

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

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-keycloak-docker-compose-stack	D4: 컨테이너 시작 시 JSON 으로부터 realm auto-import. `--import-realm` 옵션의 존재·동작과, import 디렉토리 경로 `/opt/keycloak/data/import/`(컨테이너 기준)가 공식 문서에 verbatim 명시됨을 근거로 제공. 이전엔 이 D4가 `UNSUPPORTED_DECISION`으로 라벨되어 있었음 — 본 자료로 근거 보강.

출처 / Source

원본 URL: https://www.keycloak.org/server/importExport
아카이브 URL: (미제공)
저자 / 조직: Keycloak Team (Keycloak — a Cloud Native Computing Foundation incubation project)
발행일: 명시 없음 (페이지 상단 버전 셀렉터: "Nightly" / "26.7.0" — fetch 시점 기준 최신/nightly 버전 문서로 추정, 특정 patch 버전 pin 여부는 페이지에서 명시 안 됨)
마지막 확인일: 2026-07-16

왜 저장했는지 / Why archived

feature-keycloak-docker-compose-stack branch의 D4(realm JSON auto-import 채택)가 --import-realm 옵션과 import 경로 /opt/keycloak/data/import/를 공식 인용 없이 사용하고 있어 UNSUPPORTED_DECISION으로 표시되어 있었다. 본 페이지가 그 옵션·경로·재-import 시 동작(skip)을 공식적으로 직접 진술하므로, 해당 결정의 근거 문서로 보관한다.

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

"You are also able to import realms when the server is starting by using the --import-realm option."

"When you set the --import-realm option, the server is going to try to import any realm configuration file from the data/import directory. Only regular files using the .json extension are read from this directory, sub-directories are ignored."

"For the Keycloak containers, the import directory is /opt/keycloak/data/import"

"If a realm already exists in the server, the import operation is skipped. The main reason behind this behavior is to avoid re-creating realms and potentially lose state between server restarts."

"By default, the --override option is set to true so that realms are always overridden with the new configuration."

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
KC-IMPORT-C1	`--import-realm` 옵션을 `bin/kc.[sh\|bat] start --import-realm` 형태로 사용하면, 서버 시작 시 realm 설정 파일을 import 시도한다.	"You are also able to import realms when the server is starting by using the --import-realm option."	`official-vendor-doc`	Keycloak 서버 시작 시 CLI 플래그 `--import-realm` 의 존재와 목적	공식 컨테이너 이미지(`quay.io/keycloak/keycloak`)의 기본 entrypoint/CMD 가 이 플래그를 어떻게 전달받는지는 이 페이지 범위 밖 (별도 Docker 페이지 확인 필요)
KC-IMPORT-C2	`--import-realm` 설정 시 서버는 (일반) `data/import` 디렉토리, 컨테이너 환경에서는 `/opt/keycloak/data/import` 디렉토리에서 `.json` 확장자 파일만 읽는다. sub-directory 는 무시된다.	"When you set the --import-realm option, the server is going to try to import any realm configuration file from the data/import directory. Only regular files using the .json extension are read from this directory, sub-directories are ignored." + "For the Keycloak containers, the import directory is /opt/keycloak/data/import"	`official-vendor-doc`	branch D4 의 `/opt/keycloak/data/import/` 경로 주장을 직접 뒷받침 — volume mount 대상 디렉토리 확정	정확한 patch 버전(예: 26.x 의 특정 마이너)에서 경로가 변경되지 않았는지는 이 페이지의 버전 셀렉터만으로 확정 불가 (fetch 시점엔 Nightly/26.7.0 셀렉터만 확인, 명시적 patch pin 없음)
KC-IMPORT-C3	서버에 이미 동일 realm 이 존재하면 `--import-realm` 의 import 동작은 skip 되며(overwrite 아님), 이는 서버 재시작 사이 상태 손실을 피하기 위함이다. 강제 재생성하려면 서버 시작 전 별도 `import` 명령을 명시적으로 실행해야 한다.	"If a realm already exists in the server, the import operation is skipped. The main reason behind this behavior is to avoid re-creating realms and potentially lose state between server restarts."	`official-vendor-doc`	branch D4 의 "환경 reset 후 realm 설정 즉시 복원" 목적과의 정합성 확인 — 단, 이는 realm 이 이미 존재하는 경우의 skip 동작이며, `docker compose down -v` 로 postgres volume 자체가 삭제되면 realm 이 존재하지 않으므로 정상적으로 재-import 됨 (이 추론은 이 quote 자체가 아니라 volume lifecycle 에 대한 별도 추론)	이 skip 동작이 부분적으로만 일치하는 realm(예: JSON 파일은 수정됐지만 realm 이름은 동일)에 대해서도 skip 되는지, 즉 diff 기반 병합을 하지 않는다는 것 외에 세부 비교 로직까지는 진술하지 않음
KC-IMPORT-C4	(참고, export 대응) 별도의 오프라인 `import --dir`/`--file` CLI 명령은 `--import-realm` 스타트업 옵션과 달리 `--override` 기본값이 true 라서 기존 realm 을 항상 덮어쓴다 — 두 import 경로(startup auto-import vs offline import 명령)는 충돌 처리 기본값이 반대다.	"By default, the --override option is set to true so that realms are always overridden with the new configuration."	`official-vendor-doc`	`--import-realm`(skip) 과 `import --dir --override`(overwrite 기본) 를 혼동하지 않도록 구분하는 근거	어느 메커니즘이 docker-compose 자동 프로비저닝에 더 적합한지는 이 문서가 판단하지 않음 (프로젝트 결정 사항)

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- KC-IMPORT-C1: --import-realm 옵션이 서버 시작 시 realm import 를 트리거한다는 것
- KC-IMPORT-C2: 컨테이너 환경의 import 디렉토리가 /opt/keycloak/data/import 라는 것 (branch D4 의 volume mount target 경로 근거)
- KC-IMPORT-C3: 기존 realm 이 있으면 import 가 skip(멱등) 된다는 것
- KC-IMPORT-C4: --import-realm 과 import --dir --override 는 서로 다른 충돌 처리 기본값을 가진다는 것
이 자료가 증명하지 않는 것:
- Keycloak Docker 컨테이너 이미지의 기본 entrypoint/CMD 가 --import-realm 플래그를 자동으로 전달하는지 여부 (별도 keycloak-server-containers-docker / keycloak-getting-started-docker 자료 확인 필요 — 본 branch 의 Sources 에 이미 등록됨)
- docker compose down -v 로 volume 을 삭제한 뒤 재기동 시 정확한 재-import 동작 (skip 조건은 "realm 이 이미 존재"이므로 volume 삭제 시 정상적으로 재-import 될 것으로 추론되나, 이 페이지 자체가 volume lifecycle 을 언급하지 않음)
- Keycloak 26.x 특정 patch 버전에서 경로/옵션이 변경되지 않았다는 보장 (페이지는 버전 셀렉터만 노출, fetch 시점 버전 pin 불명확)
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- docker compose up -d 후 Admin UI 에서 realm 자동 import 확인 (branch note 의 ## Claims To Verify 표에 이미 등재된 planned 항목과 연결)
- quay.io/keycloak/keycloak:26.x 이미지가 start-dev + --import-realm 조합을 command line 에서 어떻게 받는지 (예: command: start-dev --import-realm) 별도 컨테이너 문서로 검증

메모 / Notes

나중에 wiki로 옮길 때 참고할 짧은 메모. 검증되지 않은 내 추론은 여기에 두지 말 것.

페이지 상단에 버전 셀렉터("Nightly" / "26.7.0")가 있음 — fetch 시 특정 버전을 고정 선택하지 않았으므로, 정확한 버전 고정 확인이 필요하면 URL 에 버전 파라미터를 명시해 재확인 권장.
--import-realm(skip on exists) 과 import --dir --override(overwrite 기본) 는 이름이 비슷해 혼동하기 쉬움 — branch D4 는 전자(--import-realm)를 사용하므로 skip 시맨틱이 적용됨.
Admin Console 을 통한 partial import 는 별도 충돌 처리 옵션(Fail import / Skip / Overwrite)을 제공하나, 이는 CLI/startup import 와 별개의 메커니즘 — branch D4 범위 밖.

raw/official-docs/keycloak-server-containers-docker — Keycloak Docker 컨테이너 공식 문서 (KC_* 환경 변수, 같은 branch Sources)
raw/official-docs/keycloak-getting-started-docker — Docker quickstart (같은 branch Sources)

9.2 KiB Raw Blame History