llm-wiki/raw/official-docs/docker-compose-networking-extra-hosts-official.md

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

title	source_type	url	archive_url	related_branches	related_projects	tags	created
official-doc / Docker Compose — Networking (Default Service-Name DNS Discovery & extra_hosts / host-gateway)	official-doc	https://docs.docker.com/compose/how-tos/networking/		feature-keycloak-iss-claim-hostname-mismatch	keycloak-patterns	official-doc keycloak-patterns networking docker	2026-07-17

Docker Compose — Networking (Default Service-Name DNS Discovery & extra_hosts / host-gateway)

Layer: raw/ — 외부 자료(공식 문서)의 원문 발췌·출처 기록. Docker Compose 공식 문서의 (1) 기본 네트워크에서 서비스명이 별도 설정 없이 DNS 로 발견되는 동작과 (2) extra_hosts/host-gateway 를 이용한 custom hostname→IP 매핑 메커니즘을 다룬다.

source_type 허용값

frontmatter source_type: 은 official-doc — Docker Compose 공식 레퍼런스 문서.

Parent / 활용 branch

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-keycloak-iss-claim-hostname-mismatch	해결 방안 (A)/(C) 의 extra_hosts + host-gateway 메커니즘 공식 명세, 그리고 해결 방안 (F)(Spring jwk-set-uri 를 keycloak:8080 로 지정)의 도달성 근거 — Compose 기본 서비스명 DNS 가 별도 설정 없이 동작한다는 공식 근거

출처 / Source

• 원본 URL: https://docs.docker.com/compose/how-tos/networking/
• 아카이브 URL: (미제공)
• 저자 / 조직: Docker, Inc. (공식 Docker Compose 문서)
• 발행일: (페이지에 명시된 발행일 확인 불가 — 공식 docs.docker.com 상시 갱신 페이지)
• 마지막 확인일: 2026-07-17

왜 저장했는지 / Why archived

단일 EC2/로컬 docker-compose 환경에서 backend 가 Keycloak 의 JWKS 를 별도 hostname 설정 없이 http://keycloak:8080 로 fetch 할 수 있다는 것(해결 방안 F)과, extra_hosts/host-gateway 로 custom hostname 을 컨테이너에 주입하는 메커니즘(해결 방안 A/C)의 공식 근거를 보관하기 위해.

핵심 인용 / Key quotes (verbatim)

[§Default network and service discovery, fetched line 24] "Each container for a service joins the default network and is both reachable by other containers on that network, and discoverable by its service name."

[§Default network and service discovery, fetched line 25] "Each service registers its name with an internal DNS server, so containers can reach each other using the service name directly. No IP addresses or manual configuration is needed."

[§Custom DNS with extra_hosts, fetched line 83] "You can add custom hostname-to-IP mappings to a container's /etc/hosts file using extra_hosts. This is useful when a service needs to resolve a hostname that isn't registered in Docker's internal DNS. For example, a fixed-IP dependency or a staging endpoint:"

[§Custom DNS with extra_hosts, fetched line 85] "To map a hostname dynamically to the host machine's IP, use the special host-gateway value:"

[§Custom DNS with extra_hosts, fetched line 87] "On Linux, host-gateway resolves to the host's IP on the default bridge network. On Mac and Windows, Docker automatically provides this, host-gateway resolves to the same internal IP address as host.docker.internal."

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
DOCKER-COMPOSE-NET-C1	기본 Compose 네트워크에 join 한 컨테이너는 다른 컨테이너로부터 도달 가능(reachable)하고, 자신의 서비스명으로 발견 가능(discoverable)하다	"Each container for a service joins the default network and is both reachable by other containers on that network, and discoverable by its service name."	official-vendor-doc	docker compose up 이 생성하는 기본 <project-name>_default bridge 네트워크에 join 한 모든 서비스	network_mode: host/none/커스텀 external 네트워크 미가입 상태 등 기본 네트워크를 벗어난 구성에서의 동작은 증명하지 않음
DOCKER-COMPOSE-NET-C2	각 서비스는 자신의 이름을 internal DNS server 에 등록하며, 컨테이너는 IP 주소나 별도 수동 설정 없이 서비스명으로 직접 서로 도달할 수 있다	"Each service registers its name with an internal DNS server, so containers can reach each other using the service name directly. No IP addresses or manual configuration is needed."	official-vendor-doc	backend 컨테이너가 http://keycloak:8080 처럼 서비스명을 hostname 으로 사용해 같은 기본 네트워크의 Keycloak 컨테이너에 도달하는 것(해결 방안 F 의 핵심 근거) — 두 서비스가 같은 Compose 프로젝트의 동일 기본 네트워크에 있다는 전제	서비스가 다른 custom network 로 분리되어 있거나 network_mode: host 를 쓰는 경우까지 이 동작이 성립한다는 것은 증명하지 않음. JWT iss claim 값 자체(토큰에 박히는 issuer URL)와는 별개 문제 — 이 claim 은 "backend 가 JWKS 를 fetch 할 수 있는지"만 증명하며, KC_HOSTNAME 이 결정하는 iss claim 값 일치 여부는 증명하지 않음
DOCKER-COMPOSE-NET-C3	extra_hosts 는 컨테이너의 /etc/hosts 파일에 custom hostname-to-IP 매핑을 추가하는 옵션이며, Docker 내부 DNS 에 등록되지 않은 hostname(예: 고정 IP 의존성, staging endpoint)을 해석해야 할 때 유용하다	"You can add custom hostname-to-IP mappings to a container's /etc/hosts file using extra_hosts. This is useful when a service needs to resolve a hostname that isn't registered in Docker's internal DNS."	official-vendor-doc	extra_hosts 로 api.staging, cache.internal, host.docker.internal 같은 Docker 내부 DNS 에 없는 신규 hostname 을 매핑하는 시나리오 (해결 방안 A/C 의 메커니즘 근거)	extra_hosts 가 base 이미지의 기존 /etc/hosts entry(예: 127.0.0.1 localhost)를 재매핑(override)할 때 어느 쪽이 우선하는지는 이 페이지가 다루지 않음 — 본문 예시는 전부 신규 hostname 추가 사례뿐, localhost 자체를 재매핑하는 사례는 없음
DOCKER-COMPOSE-NET-C4	host 머신의 IP 를 동적으로 매핑하려면 extra_hosts 에 특수 값 host-gateway 를 사용한다	"To map a hostname dynamically to the host machine's IP, use the special host-gateway value:"	official-vendor-doc	extra_hosts: ["<hostname>:host-gateway"] 형태로 host IP 를 몰라도 동적으로 매핑해야 하는 모든 시나리오	host-gateway 를 지원하는 최소 Docker Engine/Compose 버전은 이 페이지에 명시되어 있지 않음 — 버전 요구사항은 별도 release notes 확인 필요
DOCKER-COMPOSE-NET-C5	Linux 에서 host-gateway 는 기본 bridge 네트워크에서의 host IP 로 해석되고, Mac/Windows 에서는 Docker 가 자동으로 이를 제공하며 host.docker.internal 과 동일한 internal IP 로 해석된다	"On Linux, host-gateway resolves to the host's IP on the default bridge network. On Mac and Windows, Docker automatically provides this, host-gateway resolves to the same internal IP address as host.docker.internal."	official-vendor-doc	Linux 단일 EC2 환경(본 branch 의 실 배포 대상) vs macOS/Windows Docker Desktop 학습 환경 간 host-gateway 해석 차이 비교	이 차이가 발생하는 정확한 내부 구현(예: Docker Desktop 의 VM 네트워크 계층)은 다루지 않으며, default bridge network 가 아닌 custom bridge/overlay 네트워크에서의 host-gateway 해석은 이 페이지가 직접 증명하지 않음

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:
  • DOCKER-COMPOSE-NET-C1, DOCKER-COMPOSE-NET-C2: Compose 기본 네트워크에 join 한 서비스는 별도 설정 없이 서비스명으로 서로 발견·도달 가능 (해결 방안 F 의 도달성 근거)
  • DOCKER-COMPOSE-NET-C3, DOCKER-COMPOSE-NET-C4, DOCKER-COMPOSE-NET-C5: extra_hosts 로 custom hostname 을 /etc/hosts 에 추가하는 메커니즘과 host-gateway 특수 값의 Linux vs Mac/Windows 해석 차이 (해결 방안 A/C 의 메커니즘 근거)
• 이 자료가 증명하지 않는 것:
  • extra_hosts 로 localhost 자체를 재매핑했을 때 base 이미지의 기존 127.0.0.1 localhost entry 와의 우선순위 — 이 페이지는 신규 hostname 추가 예시(api.staging, host.docker.internal 등)만 다루며 기존 entry 재매핑 사례를 다루지 않음. 본 branch 해결 방안 (C) 의 핵심 리스크이므로 별도 실측 검증 필요
  • host-gateway 지원 최소 Docker 버전 — 버전 정보는 이 페이지 소관이 아니라 release notes 소관
  • JWT iss claim 값 자체의 일치 여부(=KC_HOSTNAME 이 결정하는 issuer URL 문제) — 이 자료는 "backend 가 Keycloak 에 네트워크적으로 도달 가능한지"만 증명하며, 토큰에 박히는 iss 문자열이 backend 의 issuer-uri 기대값과 일치하는지는 별개 문제(본 branch의 D1/D5, Keycloak hostname guide 소관)
• 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  • 실제 docker-compose 환경에서 backend 컨테이너가 extra_hosts: ["localhost:host-gateway"] 설정 후 /etc/hosts 를 열어 기존 127.0.0.1 localhost entry 가 override 되는지, 아니면 두 entry 가 공존해 첫 번째 것이 우선하는지 실측 (해결 방안 C 채택 전 필수 검증 — Claims To Verify 표에 추가 권장)
  • extra_hosts: host-gateway 의 최소 Docker 버전을 별도 Docker Engine release notes 로 확인

메모 / Notes

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

• 이 자료는 두 가지 서로 다른 branch 결정을 동시에 뒷받침한다: (1) 해결 방안 F — 애초에 extra_hosts/host-gateway 없이 Spring jwk-set-uri 를 keycloak:8080 (Compose 서비스명) 로 지정해도 JWKS fetch 자체는 되는지의 도달성 근거, (2) 해결 방안 A/C — localhost/host.docker.internal 을 host-gateway 로 매핑해 backend 가 호스트에 도달하는 메커니즘. 둘은 상호 배타적 해법이 아니라 "JWKS 를 어디서 fetch 하느냐"의 대안 축이므로, branch-note 의 Decision Evidence Map 에서 D2(세 해결 방안 A/B/C) 옆에 F 도 별도 옵션으로 추가하는 것을 고려할 것(현재 branch 본문의 In-scope 목록에는 F 가 명시적으로 나열되어 있지 않음 — branch-note 갱신 필요 여부는 사용자 판단).
• 추가로 봐야 할 동일 출처 페이지: Docker Engine network_mode 공식 문서 (D2 의 network_mode: host Linux-only 진술과 최소 Docker 버전 요구사항을 직접 뒷받침하려면 별도 raw 필요 — 현재 branch-note Claims To Verify 에 needs-confirmation 으로 남아있음).

Related / 관련

• raw/official-docs/docker-port-publishing-loopback-bind-official — 같은 Docker 공식 문서군, host-boundary 포트 노출 관련 (다른 branch 근거)
• raw/official-docs/keycloak-hostname-configuration — 본 branch 의 다른 Source. KC_HOSTNAME 이 결정하는 iss claim 값 자체의 공식 근거 (본 자료의 네트워크 도달성 근거와 상호 보완)
• 이 자료를 인용한 wiki 요약: (아직 없음)