85 lines
9.4 KiB
Markdown
85 lines
9.4 KiB
Markdown
---
|
|
title: official-doc / Docker Engine 20.10 Release Notes — host.docker.internal on Linux (dockerd) + host-gateway BuildKit fix
|
|
source_type: official-doc
|
|
url: https://docs.docker.com/engine/release-notes/20.10/
|
|
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 Engine 20.10 Release Notes — host.docker.internal on Linux (dockerd) + host-gateway BuildKit fix
|
|
|
|
> Layer: `raw/` — 외부 자료(공식 문서)의 원문 발췌·출처 기록.
|
|
> Docker Engine 20.10 시리즈 release notes 중 (1) Linux `dockerd` 에서 `host.docker.internal` 지원이 도입된 릴리즈, (2) `--add-host=host.docker.internal:host-gateway` 조합이 BuildKit 활성화 시 실패하던 버그와 그 수정 릴리즈를 다룬다.
|
|
|
|
## source_type 허용값
|
|
|
|
frontmatter `source_type:` 은 `official-doc` — Docker Engine 공식 release notes (docs.docker.com).
|
|
|
|
## Parent / 활용 branch
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-keycloak-iss-claim-hostname-mismatch]] | 해결 방안 (A)/(C) 가 요구하는 `host-gateway`/`host.docker.internal` 의 최소 Docker Engine 버전 확정 — branch 본문 "마주친 문제" 의 출처 없는 "최소 Docker 20.10+" 메모를 공식 release notes 로 confirm(부분) — 단, `host.docker.internal` 자체의 dockerd/Linux 지원 시작 버전은 confirm 되나, `host-gateway` 라는 리터럴 값의 도입 버전은 이 페이지가 명시적으로 진술하지 않음(아래 Usage Boundaries 참조) |
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://docs.docker.com/engine/release-notes/20.10/
|
|
- 아카이브 URL: (미제공)
|
|
- 저자 / 조직: Docker, Inc. (공식 Docker Engine release notes)
|
|
- 발행일: 페이지 자체는 상시 갱신되는 aggregated release notes. 인용한 개별 항목의 발행일은 각 버전 heading 에 명시됨 — `20.10.0` → `2020-12-08`, `20.10.23` → `2023-01-19`.
|
|
- 마지막 확인일: 2026-07-17
|
|
|
|
## 왜 저장했는지 / Why archived
|
|
|
|
branch `feature-keycloak-iss-claim-hostname-mismatch` 의 해결 방안 (A)/(C) 가 전제하는 "`extra_hosts: host-gateway` 는 Docker 20.10+ 에서 동작한다" 는 branch 본문의 출처 없는 메모를 공식 Docker Engine release notes 로 검증하기 위해. 조사 결과 `host.docker.internal` 의 Linux dockerd 지원은 20.10.0 에서 명시적으로 확인되나, `host-gateway` 리터럴 자체의 도입 버전은 이 페이지 텍스트만으로는 확정할 수 없다(아래 C2/Usage Boundaries).
|
|
|
|
## 핵심 인용 / Key quotes (verbatim)
|
|
|
|
> [§20.10.0 / Networking, 2020-12-08] "Support host.docker.internal in dockerd on Linux" (moby/moby#40007)
|
|
|
|
> [§20.10.23 / Bug fixes and enhancements, 2023-01-19] "Fix an issue where `docker build` would fail when using `--add-host=host.docker.internal:host-gateway` with BuildKit enabled" (moby/moby#44650)
|
|
|
|
> [§20.10.0 heading + date] "20.10.0" / "2020-12-08"
|
|
|
|
> [§20.10.23 heading + date] "20.10.23" / "2023-01-19"
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| DOCKER-2010-C1 | Docker Engine 20.10.0 (2020-12-08 릴리즈) 의 Networking 항목에서 Linux 상의 `dockerd` 에 `host.docker.internal` 지원이 추가되었다고 명시 | "Support host.docker.internal in dockerd on Linux" | `official-vendor-doc` | Docker Engine(`dockerd`) 의 **Linux** 빌드에서 `host.docker.internal` 이름 해석 기능이 20.10.0 부터 존재함을 확인 | (1) `host-gateway` 라는 리터럴 문자열/값 자체가 이 항목과 같은 릴리즈(20.10.0)에서 도입되었다는 것 — 이 페이지 20.10.0 항목 텍스트에는 "host-gateway" 문자열이 등장하지 않음. (2) Docker Compose `extra_hosts:` YAML 문법의 존재/버전 요구사항 — 그건 Compose spec 소관 ([[raw/official-docs/docker-compose-networking-extra-hosts-official]]). (3) Docker Desktop(Mac/Windows) 에서의 `host.docker.internal` 동작 — 이 항목은 Linux dockerd 한정이며 Desktop 은 별도 VM 네트워크 계층 사용 |
|
|
| DOCKER-2010-C2 | Docker Engine 20.10.23 (2023-01-19 릴리즈) 의 Bug fixes and enhancements 항목에서, `docker build` 가 BuildKit 활성화 상태로 `--add-host=host.docker.internal:host-gateway` 를 사용할 때 실패하던 버그를 수정했다고 명시 | "Fix an issue where `docker build` would fail when using `--add-host=host.docker.internal:host-gateway` with BuildKit enabled" | `official-vendor-doc` | `docker build`(BuildKit 경로) 가 `host-gateway` 리터럴을 `--add-host` 값으로 사용하는 조합에 20.10.23 이전 결함이 있었고 그 시점엔 이미 `host-gateway` 문법 자체는 존재/사용 중이었음을 간접 확인(버그 수정 대상이려면 기능이 이미 존재해야 함) | `host-gateway` 가 정확히 몇 버전에 **처음** 도입되었는지 — 이 항목은 "이미 존재하던 기능의 BuildKit 특정 결함 수정"만 서술하며 도입 시점을 진술하지 않음. `docker run`/Compose 경로(비-BuildKit)에서 동일 결함이 있었는지도 이 항목 범위 밖 |
|
|
|
|
### Strength 근거
|
|
|
|
- 두 claim 모두 Docker Engine 공식 release notes(docs.docker.com, Docker, Inc. 발행)에서 직접 인용 — `official-vendor-doc`.
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- 이 자료가 직접 증명하는 것:
|
|
- `DOCKER-2010-C1`: `host.docker.internal` 의 Linux `dockerd` 지원은 **20.10.0(2020-12-08)** 부터 공식적으로 존재.
|
|
- `DOCKER-2010-C2`: `--add-host=host.docker.internal:host-gateway` + BuildKit 조합은 **20.10.23(2023-01-19) 이전** 에 결함이 있었고, 그 시점 이전에 이미 해당 문법이 사용되고 있었음(버그 수정 대상이므로).
|
|
- 이 자료가 증명하지 않는 것:
|
|
- **`host-gateway` 리터럴 값 자체의 최초 도입 버전.** 이 페이지 전체(20.10.0 ~ 20.10.24)에서 문자열 `host-gateway` 가 등장하는 곳은 20.10.23 버그 수정 항목 단 한 곳뿐이며, 20.10.0 의 `host.docker.internal` 항목 텍스트에는 등장하지 않는다(self-grep 확인 완료). 따라서 branch 본문의 "최소 Docker 20.10+" 메모는 **`host.docker.internal`(Linux dockerd) 지원 자체는 confirm** 되지만, `host-gateway` 리터럴의 최소 버전을 이 문서만으로 20.10.0 이라고 확정할 수는 **없다** — 부분 confirm.
|
|
- Docker Compose 파일의 `extra_hosts:` YAML 문법 — 이는 Compose spec/공식 문서 소관이며, 본 project 에서는 이미 [[raw/official-docs/docker-compose-networking-extra-hosts-official]] 가 그 근거를 담당한다(해당 문서도 "host-gateway 지원 최소 Docker 버전은 이 페이지 소관 아님"이라고 명시하며 본 문서를 그 후속 조사로 기대하고 있었음).
|
|
- Docker Desktop(Mac/Windows) 의 `host.docker.internal`/`host-gateway` 동작 — 이 릴리즈 노트의 해당 항목은 명시적으로 "in dockerd on Linux" 로 범위를 한정한다. Desktop 환경은 별도 VM 네트워크 계층(예: Compose 문서의 "On Mac and Windows, Docker automatically provides this" 진술)이 적용되며 이 문서가 다루는 영역이 아니다.
|
|
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
|
|
- `host-gateway` 리터럴의 정확한 도입 버전을 확정하려면 moby/moby PR #40007(20.10.0 의 host.docker.internal PR) 원문을 직접 확인해야 한다 — 이 release notes 페이지의 텍스트만으로는 "같은 PR에서 host-gateway 값도 함께 도입되었는지"를 증명할 수 없다(합리적 추정은 가능하나 verbatim 근거 아님).
|
|
- branch 의 실 배포 대상(단일 EC2, Linux)에서 사용할 실제 Docker Engine 버전이 20.10.0 이상(이상적으로 20.10.23 이상, BuildKit 버그를 피하려면)인지 `docker version` 으로 확인 필요.
|
|
|
|
## 메모 / Notes
|
|
|
|
> 나중에 wiki로 옮길 때 참고할 짧은 메모. 검증되지 않은 내 추론은 여기에 두지 말 것.
|
|
|
|
- moby/moby PR #40007 의 제목("Support host.docker.internal in dockerd on Linux")과 Linux 에서 `host.docker.internal` 이 구현되는 일반적 메커니즘(= `--add-host` 의 특수 값)을 고려하면 `host-gateway` 리터럴도 같은 PR/릴리즈에서 함께 도입되었을 가능성이 높다 — 그러나 이 release notes 문서 자체는 그 사실을 verbatim 으로 진술하지 않으므로 **미검증 추론**으로만 남긴다. 확정하려면 GitHub PR #40007 원문 또는 moby/moby CHANGELOG 를 별도 raw 자료로 추가 조사할 것.
|
|
- 이 자료는 [[raw/official-docs/docker-compose-networking-extra-hosts-official]] 가 명시적으로 남긴 "host-gateway 지원 최소 Docker 버전을 별도 Docker Engine release notes 로 확인" 이라는 후속 조사 요청에 대한 응답으로 작성됨.
|
|
|
|
## Related / 관련
|
|
|
|
- [[raw/official-docs/docker-compose-networking-extra-hosts-official]] — 같은 branch 의 다른 Source. `extra_hosts`/`host-gateway` 의 **문법과 Linux vs Mac/Windows 해석 차이**를 다루며, "최소 버전은 이 페이지 소관 아님"이라고 명시적으로 본 문서로 위임했음.
|
|
- [[raw/official-docs/keycloak-hostname-configuration]] — 본 branch 의 또 다른 Source. `KC_HOSTNAME` 이 결정하는 `iss` claim 값 자체의 공식 근거 (본 자료의 host-gateway 네트워크 메커니즘과 상호 보완).
|
|
- 이 자료를 인용한 wiki 요약: (아직 없음)
|