donghyeon.kang/llm-wiki

Fork 0

Files

T

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

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

9.8 KiB

Raw Permalink 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 / Docker Engine — Host network driver (platform support & port-mapping behavior)

Layer: raw/ — 외부 자료(공식 문서)의 원문 발췌·출처 기록.

source_type 허용값

official-doc — Docker 공식 Engine 레퍼런스 문서.

Parent / 활용 branch

Branch 이 자료가 정당화하는 결정

raw/branch-notes/feature-keycloak-iss-claim-hostname-mismatch 해결 방안 (B) network_mode: host 의 플랫폼 제약 — branch 노트가 출처 없이 "Linux only" 라고 적은 미검증 메모를 공식 문서로 confirm/refute 하는 1차 근거. 결과: 부분 refute — Docker Engine on Linux 는 native 지원이 맞으나, Docker Desktop 4.34+ 에서도 opt-in 으로 지원됨(무조건 "동작 안 함" 아님). 단 layer 4 한정 + Enhanced Container Isolation 비호환 등 추가 제약이 있음.

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-keycloak-iss-claim-hostname-mismatch	해결 방안 (B) `network_mode: host` 의 플랫폼 제약 — branch 노트가 출처 없이 "Linux only" 라고 적은 미검증 메모를 공식 문서로 confirm/refute 하는 1차 근거. 결과: 부분 refute — Docker Engine on Linux 는 native 지원이 맞으나, Docker Desktop 4.34+ 에서도 opt-in 으로 지원됨(무조건 "동작 안 함" 아님). 단 layer 4 한정 + Enhanced Container Isolation 비호환 등 추가 제약이 있음.

출처 / Source

원본 URL: https://docs.docker.com/engine/network/drivers/host/
아카이브 URL: (미확보)
저자 / 조직: Docker, Inc. (공식 Engine 문서)
발행일: (페이지에 명시 없음 — 최종 갱신일 비공개)
마지막 확인일: 2026-07-17

왜 저장했는지 / Why archived

branch feature-keycloak-iss-claim-hostname-mismatch 의 §범위 "해결 방안 (B) network_mode: host (Docker hairpin NAT — Linux only)" 및 §마주친 문제의 "macOS/Windows Docker Desktop에서 동작 안 함 — Linux only" 진술이 출처 없는 미검증 메모였다. 이 공식 문서로 해당 진술의 현재 정확도를 판정하고, 포트 매핑(-p/--publish/ports:) 비호환 사유를 근거로 확보하기 위해 저장.

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

[§Prerequisites] "The host networking driver only works on Linux hosts, and as an opt-in feature in Docker Desktop version 4.34 and later." (line 60)

[§Platform support] "Docker Desktop version 4.34 and later (requires enabling the feature in Settings)" (line 29)

[§Limitations] "Only Linux containers are supported. Host networking does not work with Windows containers." (line 55)

[§Note] "Given that the container does not have its own IP-address when using host mode networking, port-mapping doesn't take effect, and the -p, --publish, -P, and --publish-all option are ignored, producing a warning instead:" (line 20)

[§Limitations] "The host network feature of Docker Desktop works on layer 4. This means that unlike with Docker on Linux, network protocols that operate below TCP or UDP are not supported." (line 53)

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
DOCKER-HOSTNET-C1	Host network driver 는 Linux host 에서 native 로 동작하며, Docker Desktop 4.34+ 에서는 설정에서 수동 활성화해야 하는 opt-in 기능으로 지원된다	[§Prerequisites] "The host networking driver only works on Linux hosts, and as an opt-in feature in Docker Desktop version 4.34 and later."	`official-vendor-doc`	`network_mode: host` 를 사용하는 개발 환경이 Linux host 인지 Docker Desktop(4.34+, opt-in 활성화)인지 판별	이 branch 의 실제 개발 환경이 Linux host 인지 Docker Desktop 인지, 또는 Docker Desktop 버전이 4.34 이상인지는 증명하지 않음 — 로컬 `docker version` 확인 별도 필요
DOCKER-HOSTNET-C2	Docker Desktop 에서 host networking 지원은 버전 4.34 이상이며 Settings > Resources > Network 에서 수동 활성화가 필요하다	[§Platform support] "Docker Desktop version 4.34 and later (requires enabling the feature in Settings)"	`official-vendor-doc`	Docker Desktop 사용자가 4.34 미만이면 host networking 자체가 존재하지 않음을 확인하는 근거	4.34 미만 버전에서의 정확한 동작(완전 부재 vs 다른 제약)은 이 문장만으로 세부 확인 불가
DOCKER-HOSTNET-C3	host networking 은 Windows 컨테이너에서 동작하지 않으며 Linux 컨테이너만 지원한다	[§Limitations] "Only Linux containers are supported. Host networking does not work with Windows containers."	`official-vendor-doc`	branch 의 keycloak/backend 컨테이너가 Linux 컨테이너 이미지인 경우 이 제약은 무관함을 확인	Windows 컨테이너를 아예 사용하지 않는 본 프로젝트에는 직접 영향 없음 — 이 claim 은 그 사실을 증명하는 게 아니라 제약의 존재만 증명
DOCKER-HOSTNET-C4	host network mode 에서는 컨테이너가 자체 IP 를 갖지 않으므로 port-mapping 이 작동하지 않고, `-p`/`--publish`/`-P`/`--publish-all` 옵션이 무시되며 경고가 출력된다	[§Note] "Given that the container does not have its own IP-address when using host mode networking, port-mapping doesn't take effect, and the -p, --publish, -P, and --publish-all option are ignored, producing a warning instead:"	`official-vendor-doc`	docker-compose `ports:` 매핑을 `network_mode: host` 서비스에 남겨두면 무시된다는 근거 — keycloak 서비스 compose 파일에서 `ports:` 제거 필요성의 근거	이 문장은 `docker run -p` / CLI 플래그 기준 진술이며, docker-compose YAML 의 `ports:` 키를 문자 그대로 언급하지 않음 — 동작은 기능적으로 동일하나 문서가 compose YAML 문법을 직접 지칭하지 않는다는 점은 명시해둘 것
DOCKER-HOSTNET-C5	Docker Desktop 의 host network 기능은 layer 4(TCP/UDP) 에서만 동작하며, Linux 의 Docker 와 달리 TCP/UDP 하위 계층 프로토콜은 지원하지 않는다	[§Limitations] "The host network feature of Docker Desktop works on layer 4. This means that unlike with Docker on Linux, network protocols that operate below TCP or UDP are not supported."	`official-vendor-doc`	Docker Desktop 환경에서 host networking 을 쓸 때 Linux native 구현과 기능적으로 동일하지 않음을 아는 근거	HTTP/JWT 트래픽(TCP 기반)이 이 제약의 영향을 받는지 여부는 이 문장이 직접 말하지 않음 — TCP 기반이므로 영향 없을 것이라는 추론은 이 자료의 claim 이 아니라 별도 추론(§메모에서만 다룸)

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- DOCKER-HOSTNET-C1/C2: host networking 이 Linux Engine 뿐 아니라 Docker Desktop 4.34+ 에서도 (opt-in 조건부로) 지원된다는 것. 즉 branch 노트의 "Linux only" 라는 무조건적 진술은 현재(2026-07-17 확인) 기준 부정확하다 — 정확히는 "Linux native, Docker Desktop 은 4.34+ 부터 opt-in 지원, 단 layer 4 한정".
- DOCKER-HOSTNET-C3: Windows 컨테이너는 host networking 을 지원하지 않는다는 것.
- DOCKER-HOSTNET-C4: host mode 에서 포트 매핑 CLI 플래그가 무시되고 경고가 출력된다는 것.
- DOCKER-HOSTNET-C5: Docker Desktop 구현이 layer 4 로 제한된다는 것.
이 자료가 증명하지 않는 것:
- Keycloak 의 iss claim 생성 로직이나 KC_HOSTNAME 동작 — Docker 문서는 Keycloak 을 언급하지 않는다.
- Spring Security Resource Server 의 issuer-uri 검증 방식 — 전혀 다른 스택.
- extra_hosts: host-gateway 의 최소 Docker 버전(20.10+) — 이 페이지에는 해당 진술 없음 (branch 노트의 다른 미검증 메모는 이 자료로 해결되지 않음, 별도 자료 필요).
- macOS/Windows Docker Desktop 에서 host networking 이 "완전히 동작 안 한다"는 절대 진술 — 오히려 이 자료는 정반대로 4.34+ 에서 opt-in 지원됨을 명시한다.
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- 실제 개발 환경이 Linux Engine 인지 Docker Desktop 인지, Docker Desktop 이라면 버전이 4.34 이상인지 (docker version 로 확인).
- Docker Desktop 이라면 Settings > Resources > Network 에서 "Enable host networking" 이 실제로 켜져 있는지.
- Enhanced Container Isolation 이 활성화된 환경인지 (활성화 시 host networking 자체와 상호 배타적).

메모 / Notes

branch 노트 §마주친 문제의 "network_mode: host 사용 시 macOS/Windows Docker Desktop에서 동작 안 함 — Linux only" 메모는 부분적으로만 맞다. 정확히는: Linux Engine 은 native 지원, Docker Desktop 은 4.34+ 부터 opt-in 지원(수동 활성화 필요) — "전혀 동작 안 함"은 아님. 단, 이 자료가 Docker Desktop 버전을 명시하지 않으므로, branch 작성 시점(2026-05-25)의 Docker Desktop 버전이 4.34 미만이었을 가능성은 배제 못함 — 그 경우 당시 관찰은 사실이었을 수 있다. 이는 미검증 추론이며 검증하려면 branch 작성 시점의 Docker Desktop 버전 확인이 필요하다.
HTTP/JWT 트래픽이 TCP 기반이라 layer-4-only 제약(DOCKER-HOSTNET-C5)의 영향을 받지 않을 것이라는 판단은 이 자료가 직접 말하지 않는 미검증 추론이다 — Claims Extracted 표에는 넣지 않았음.
추가로 봐야 할 동일 출처 페이지: Docker Compose 공식 스펙의 network_mode: host 항목(compose YAML 문법 기준 진술 확보), extra_hosts / host-gateway 공식 문서(별도 branch 미검증 메모 해결용).

raw/official-docs/keycloak-hostname-configuration — 같은 branch 의 1차 근거 (Keycloak KC_HOSTNAME 및 iss claim 공식 설명)
raw/official-docs/docker-port-publishing-loopback-bind-official — 같은 vendor(Docker) 의 포트 publishing 관련 공식 문서

9.8 KiB Raw Permalink Blame History