llm-wiki/raw/official-docs/docker-port-publishing-loopback-bind-official.md

---
title: official-doc / Docker Engine — Container Port Publishing (default 0.0.0.0 vs loopback bind)
source_type: official-doc
url: https://docs.docker.com/engine/network/port-publishing/
archive_url:
related_branches: [feature-keycloak-header-spoofing-defense]
related_projects: [keycloak-patterns]
tags: [official-doc, keycloak-patterns, networking, security, docker]
created: 2026-07-16
---

# Docker Engine — Container Port Publishing (default 0.0.0.0 vs loopback bind)

> Layer: `raw/` — 외부 자료(공식 문서)의 원문 발췌·출처 기록.
> Docker Engine 공식 문서의 `-p`/`--publish` 포트 퍼블리싱 기본 동작(모든 host 주소로 열림)과 loopback(`127.0.0.1`) bind 로 접근 범위를 Docker host 로 제한하는 옵션을 다룬다.

## source_type 허용값

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

## Parent / 활용 branch

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-keycloak-header-spoofing-defense]] | D4 — 단일 EC2 co-located 배포에서 backend 의 published port 를 `127.0.0.1`(loopback) 로 bind 하면 Docker host 에서만 접근 가능해지고, `0.0.0.0` publish 는 "insecure by default" — Security Group(ENI 경계) 이 커버하지 못하는 host-boundary 계층의 방어라는 근거 |

## 출처 / Source

- 원본 URL: https://docs.docker.com/engine/network/port-publishing/
- 아카이브 URL: (미제공)
- 저자 / 조직: Docker, Inc. (공식 Docker Engine 문서)
- 발행일: (페이지에 명시된 발행일 확인 불가 — 공식 docs.docker.com 상시 갱신 페이지)
- 마지막 확인일: 2026-07-16

## 왜 저장했는지 / Why archived

단일 EC2 에 Keycloak + backend 가 co-located 될 때, EC2 Security Group(ENI 경계)만으로는 같은 host 안에서 도달 가능한 포트를 막을 수 없다. Docker 의 `-p 127.0.0.1:HOST_PORT:CONTAINER_PORT` bind 가 SG 와 별개인 **host-boundary** 계층 방어라는 것을 공식 문서로 확인하기 위해 보관.

## 핵심 인용 / Key quotes (verbatim)

> [docs.docker.com/engine/network/port-publishing — default bind 설명, fetched line 40] "By default, when a container's ports are mapped without any specific host address, the Docker daemon publishes ports to all host addresses (`0.0.0.0` and `[::])."

> [docs.docker.com/engine/network/port-publishing — `-p` 예시, fetched line 42] "For example, `docker run -p 8080:80 [...]` creates a mapping between port 8080 on any address on the Docker host, and the container's port 80."

> [docs.docker.com/engine/network/port-publishing — 보안 경고, fetched line 16 / 44] "Publishing container ports is insecure by default. Meaning, when you publish a container's ports it becomes available not only to the Docker host, but to the outside world as well."

> [docs.docker.com/engine/network/port-publishing — loopback 제한, fetched line 46] "If you include the localhost IP address (`127.0.0.1`, or `::1`) with the publish flag, only the Docker host can access the published container port."

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| DOCKER-PORT-PUB-C1 | 특정 host 주소를 지정하지 않고 포트를 매핑하면, Docker daemon 은 기본적으로 모든 host 주소(`0.0.0.0`, `[::]`)에 포트를 publish 한다 | "By default, when a container's ports are mapped without any specific host address, the Docker daemon publishes ports to all host addresses (`0.0.0.0` and `[::])." | `official-vendor-doc` | host IP prefix 없이 `-p HOST_PORT:CONTAINER_PORT` 또는 동등한 docker-compose `ports:` 매핑을 사용하는 모든 단일 Docker Engine host | Docker Swarm ingress mode 의 routing mesh 동작이나 Docker Desktop 의 VM 네트워크 계층에서의 차이는 다루지 않음 |
| DOCKER-PORT-PUB-C2 | `docker run -p 8080:80` 예시는 Docker host 의 **모든 주소**에서 포트 8080 을 컨테이너 포트 80 에 매핑한다는 것을 공식 예시로 보여준다 | "For example, `docker run -p 8080:80 [...]` creates a mapping between port 8080 on any address on the Docker host, and the container's port 80." | `official-reference` | `-p` flag 문법 이해 (host IP 생략 시 동작) | 특정 애플리케이션의 보안 요구사항 충족 여부는 증명하지 않음 |
| DOCKER-PORT-PUB-C3 | 컨테이너 포트를 publish 하는 것은 기본적으로 안전하지 않다(insecure by default) — publish 하면 Docker host 뿐 아니라 외부 세계에서도 접근 가능해진다 | "Publishing container ports is insecure by default. Meaning, when you publish a container's ports it becomes available not only to the Docker host, but to the outside world as well." | `official-vendor-doc` | host IP 제한 없이 `-p` 를 사용하는 모든 배포 시나리오에 대한 일반 경고 | 어떤 추가 완화책(SG, 방화벽, NetworkPolicy 등)이 충분한지는 증명하지 않음 — 이 경고는 Docker 자체의 기본 동작에 대한 것 |
| DOCKER-PORT-PUB-C4 | publish flag 에 localhost IP(`127.0.0.1` 또는 `::1`)를 포함시키면, 오직 Docker host 만 publish 된 컨테이너 포트에 접근할 수 있다 | "If you include the localhost IP address (`127.0.0.1`, or `::1`) with the publish flag, only the Docker host can access the published container port." | `official-vendor-doc` | `-p 127.0.0.1:HOST_PORT:CONTAINER_PORT` 형태의 loopback bind, 단일 host Docker Engine 배포 | Docker host 자체에 접근 가능한 다른 프로세스/사용자로부터의 접근까지 막는다는 뜻은 아님(loopback 은 host-boundary 방어이지, host 내부 프로세스 간 격리는 아님). Swarm ingress mode 에서의 동일 동작은 증명하지 않음 |

## Usage Boundaries / 적용 경계

- 이 자료가 직접 증명하는 것:
  - `DOCKER-PORT-PUB-C1`, `DOCKER-PORT-PUB-C2`: host IP 미지정 시 Docker 가 기본적으로 `0.0.0.0`/`[::]` 전체에 publish 한다는 것
  - `DOCKER-PORT-PUB-C3`: 이 기본 동작이 "insecure by default" 라는 공식 경고
  - `DOCKER-PORT-PUB-C4`: `127.0.0.1`/`::1` loopback IP 를 publish flag 에 포함하면 접근 범위가 Docker host 로 좁혀진다는 것
- 이 자료가 증명하지 않는 것:
  - EC2 Security Group(ENI 경계)이 이 host-boundary 방어를 대체하거나 불필요하게 만든다는 것 — 오히려 이 문서는 SG 와 무관한 **별개 계층**(host 자체의 listen 주소)을 설명할 뿐이다
  - loopback bind 만으로 같은 host 안의 다른 프로세스/컨테이너로부터의 접근까지 차단된다는 것(이건 host 내부 격리 문제이며 별도 검증 필요)
  - Docker Swarm 모드의 routing mesh(ingress) 에서도 동일하게 동작한다는 것
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - 실제 `docker-compose.yml` 에서 backend 서비스의 `ports:` 를 `127.0.0.1:8080:8080` 형태로 bind 했을 때, EC2 인스턴스 로컬에서만 curl 성공하고 외부 IP 로는 실패하는지 실측 검증 (branch note 의 `Claims To Verify` 표에 해당 항목 추가 필요)

## 메모 / Notes

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

- D4 의 핵심 논리는 "SG = ENI(네트워크 인터페이스) 경계 방어, loopback bind = host 프로세스의 listen 주소 자체를 제한하는 방어" 로 계층이 다르다는 것. 이 자료는 그 두 번째 계층(host listen 주소)의 공식 근거만 제공한다. SG 와의 관계(계층이 다르다는 비교 주장)는 이 문서 자체가 말하는 바가 아니라 branch-note 저자의 조합적 추론이므로, branch-note 쪽 Decision Evidence Map 에서는 별도로 "SG 비교" 부분을 UNSUPPORTED 로 표시하거나 AWS Security Group 공식 문서를 별도 raw 로 추가해 뒷받침해야 함.
- 추가로 봐야 할 동일 출처 페이지: AWS EC2 Security Group 공식 문서 (D4 의 SG 경계 비교 주장을 직접 뒷받침하려면 별도 raw 필요 — 현재 branch-note TODO 에 "검토 후보"로만 있음).

## Related / 관련

- (같은 주제의 다른 official-doc 없음 — 최초 등록)
- 이 자료를 인용한 wiki 요약: (아직 없음)