83 lines
9.2 KiB
Markdown
83 lines
9.2 KiB
Markdown
---
|
|
title: official-doc / Keycloak — Importing and exporting realms (--import-realm, directory-based auto-import)
|
|
source_type: official-doc
|
|
url: https://www.keycloak.org/server/importExport
|
|
archive_url:
|
|
related_branches: [feature-keycloak-docker-compose-stack]
|
|
related_projects: [keycloak-patterns]
|
|
tags: [official-doc, keycloak-patterns, infra, keycloak, docker]
|
|
created: 2026-07-16
|
|
---
|
|
|
|
# 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 범위 밖.
|
|
|
|
## Related / 관련
|
|
|
|
- [[raw/official-docs/keycloak-server-containers-docker]] — Keycloak Docker 컨테이너 공식 문서 (KC_* 환경 변수, 같은 branch Sources)
|
|
- [[raw/official-docs/keycloak-getting-started-docker]] — Docker quickstart (같은 branch Sources)
|