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)を直接指定します。

対応方法

  1. ユーザー定義ネットワークを作り、通信させたいコンテナを同じネットワークに参加させる
  2. 接続先にはコンテナ名(Compose ならサービス名)を指定する
  3. ポートはコンテナ側のポート番号を使う
  4. 起動順だけでなく、相手が接続を受け付けられる状態になったかどうかも考える

実装例

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 点を押さえておけば、コンテナ間通信のトラブルの大半は切り分けられます。

\ 最新情報をチェック /

コメントを残す

このサイトはスパムを低減するために Akismet を使っています。コメントデータの処理方法の詳細はこちらをご覧ください。