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

---
title: official-doc / Docker Compose — Networking (Default Service-Name DNS Discovery & extra_hosts / host-gateway)
source_type: official-doc
url: https://docs.docker.com/compose/how-tos/networking/
archive_url:
related_branches: [feature-keycloak-iss-claim-hostname-mismatch]
related_projects: [keycloak-patterns]
tags: [official-doc, keycloak-patterns, networking, docker]
created: 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 요약: (아직 없음)