Dockerのコンテナ間通信入門:ネットワーク設定と名前解決の仕組み
概要
Docker で Web サーバー・アプリ・DB を別々のコンテナに分けたとき、多くの人が最初につまずくのが「コンテナ同士が繋がらない」問題です。原因は主に次の 3 つです。
- ネットワークの種類(デフォルト bridge かユーザー定義ネットワークか)
- 接続先の指定(
localhostを使っている、公開側のポートを使っている) - 相手のコンテナが接続を受け付けられる状態になっていない
この記事では、Docker の内蔵 DNS による名前解決の仕組みを説明したうえで、docker run と Docker Compose それぞれでのコンテナ間通信の設定方法と確認方法を紹介します。
環境
(仮置き: 以下の環境を想定しています。バージョンによって細かい挙動が違う場合があります)
- Docker Engine 24 以降
- Docker Compose v2(
docker composeコマンド) - Linux / macOS(Docker Desktop)
よくある「繋がらない」パターン
パターン1: コンテナ名で引けない
docker run -d --name web nginx:1.27 docker run --rm busybox:1.36 wget -qO- http://web # wget: bad address 'web'
web というコンテナが動いているのに、その名前が解決できません。
パターン2: localhost で繋がらない
ホスト上で直接動かしていたときの DB_HOST=localhost のままアプリをコンテナにすると、DB に繋がらなくなります。
パターン3: ポート番号が違う
ports: "15432:5432" で公開している DB に対して、アプリ側から db:15432 で繋ごうとして失敗します。
原因
コンテナの localhost はコンテナ自身
コンテナごとに独立したネットワーク名前空間があります。コンテナの中の localhost(127.0.0.1)が指すのはそのコンテナ自身で、ホストや他のコンテナではありません。
デフォルト bridge には名前解決がない
ネットワークを指定せずに docker run したコンテナは、デフォルトの bridge ネットワークに繋がります。ここでは IP アドレスでは通信できますが、コンテナ名での名前解決はできません(--link はレガシー機能という扱いです)。
ユーザー定義ネットワークには内蔵 DNS がある
docker network create で作ったネットワークでは、Docker の内蔵 DNS サーバー(コンテナから見たアドレスは 127.0.0.11)が使えます。同じネットワークにいるコンテナ名やエイリアスを IP アドレスに変換し、外部のドメイン名はホスト側の DNS 設定に従って転送します。
ports はホストから入るための設定
"15432:5432" は「ホストの 15432 番 → コンテナの 5432 番」という転送の設定です。コンテナ同士の通信はこの転送を経由しないので、コンテナ側のポート(5432)を直接指定します。
対応方法
- ユーザー定義ネットワークを作り、通信させたいコンテナを同じネットワークに参加させる
- 接続先にはコンテナ名(Compose ならサービス名)を指定する
- ポートはコンテナ側のポート番号を使う
- 起動順だけでなく、相手が接続を受け付けられる状態になったかどうかも考える
実装例
docker run の場合
# ユーザー定義ネットワークを作成 docker network create demo-net # 同じネットワークに参加させて起動 docker run -d --name web --network demo-net nginx:1.27 # 別コンテナからコンテナ名で疎通確認 docker run --rm --network demo-net busybox:1.36 wget -qO- http://web # → nginx のデフォルトページの HTML が返る
起動済みのコンテナは、後からネットワークに追加できます。
docker network connect demo-net existing-container
コンテナ名とは別の名前でも引けるようにするには、エイリアスを付けます。
docker run -d --name pg1 --network demo-net --network-alias database \ -e POSTGRES_PASSWORD="$POSTGRES_PASSWORD" postgres:16 # 同じネットワーク内からは "pg1" でも "database" でも引ける
Docker Compose の場合(最小構成)
Compose はプロジェクトごとに <プロジェクト名>_default というネットワークを自動で作り、すべてのサービスをそこに繋ぎます。そのため、何も設定しなくてもサービス名で通信できます。
# compose.yaml
services:
app:
build: ./app
environment:
DB_HOST: db # サービス名をそのままホスト名として使う
DB_PORT: "5432" # コンテナ側のポート
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} # 値は .env などから渡す
Docker Compose の場合(ネットワーク分割 + 起動待ち)
# compose.yaml
services:
web:
image: nginx:1.27
ports:
- "8080:80" # ホストから入る口はここだけ
networks:
- frontend
app:
build: ./app
environment:
DB_HOST: database
DB_PORT: "5432"
networks:
- frontend
- backend
depends_on:
db:
condition: service_healthy # DB が healthy になるまで待つ
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 5s
timeout: 3s
retries: 10
networks:
backend:
aliases:
- database
networks:
frontend:
backend:
internal: true # このネットワークからは外部に出られない
この構成での通信の可否は次のとおりです。
| 通信 | 可否 | 理由 |
|---|---|---|
| web → app | ○ | どちらも frontend に参加 |
| app → db | ○ | どちらも backend に参加(db / database で引ける) |
| web → db | × | 共通のネットワークがない |
| ホスト → db | × | ports を公開していない |
| db → インターネット | × | backend は internal: true |
別の Compose プロジェクトと通信したい場合
docker network create shared-net
services:
app:
networks:
- shared
networks:
shared:
external: true
name: shared-net
確認方法
ネットワークと参加コンテナ
docker network ls docker network inspect demo-net
inspect の結果にある Containers で、参加しているコンテナと IP アドレスを確認できます。
コンテナ内からの名前解決
# Debian / Ubuntu 系のイメージ docker compose exec app getent hosts db # Alpine / BusyBox 系のイメージ docker compose exec app nslookup db
DNS の参照先
docker compose exec app cat /etc/resolv.conf
ユーザー定義ネットワークにいれば nameserver 127.0.0.11 が出ます。
診断用コンテナを横付けする
docker run --rm -it --network <プロジェクト名>_default busybox:1.36 sh # / # nslookup db # / # wget -qO- http://app:3000/health
注意点
- IP アドレスを決め打ちしない: コンテナを作り直すと IP は変わることがあります。
container_nameは必須ではない: Compose ならサービス名で引けます。固定すると--scaleが使えなくなります。depends_onは起動順しか保証しない: 準備完了まで待つならhealthcheckとcondition: service_healthyを組み合わせます。アプリ側にもリトライ処理を入れておくと安心です。- コンテナからホストへのアクセス: Docker Desktop なら
host.docker.internalでホストに届きます。Linux の場合は次の設定が必要です。
```yaml extra_hosts:
- "host.docker.internal:host-gateway"
```
- スケール時の名前解決:
--scale app=3のように複数起動すると、サービス名に複数の IP が返ります。負荷分散が必要ならリバースプロキシを置くことを検討してください。 - Compose のネットワーク名: デフォルトのネットワーク名はプロジェクト名(ディレクトリ名)から付けられます。外から参照するときは
docker network lsで実際の名前を確認します。
まとめ
- コンテナ内の
localhostはそのコンテナ自身 - デフォルト bridge ではコンテナ名で引けないので、ユーザー定義ネットワークを使う
- 内蔵 DNS(127.0.0.11)がコンテナ名・サービス名・エイリアスを解決する
- Compose はデフォルトネットワークを自動で作るので、サービス名で通信できる
- コンテナ同士の通信ではコンテナ側のポートを使う。
portsはホストから入るための設定 - 起動待ちには
healthcheck+condition: service_healthyを使う
「同じネットワークに入れて、名前で、コンテナ側のポートに繋ぐ」。この 3 点を押さえておけば、コンテナ間通信のトラブルの大半は切り分けられます。
