Docker Composeのネットワーク設計｜サービス名での名前解決・カスタムネットワーク・external接続の実践手順

この記事のポイント

・Composeはdocker compose up時に専用ブリッジネットワークを自動作成しサービス名をDNSホスト名にする
・networks:ブロックでカスタムネットワークを定義しサービスに複数割り当てると通信経路を分離できる
・external: trueでComposeの外側に存在する既存Dockerネットワークに接続できる
・docker network inspectとdocker compose execで通信障害を迅速に切り分けられる

# docker compose up後にネットワーク一覧を確認
$ docker network ls
NETWORK ID     NAME                    DRIVER    SCOPE
a1b2c3d4e5f6   bridge                  bridge    local
f6e5d4c3b2a1   host                    host      local
9z8y7x6w5v4u   myapp_default           bridge    local

# myapp = compose.ymlのあるディレクトリ名（プロジェクト名）

# webコンテナ内でdbのホスト名を解決できることを確認
$ docker compose exec web ping -c 3 db
PING db (172.18.0.3) 56(84) bytes of data.
64 bytes from db (172.18.0.3): icmp_seq=1 ttl=64 time=0.094 ms
64 bytes from db (172.18.0.3): icmp_seq=2 ttl=64 time=0.078 ms
64 bytes from db (172.18.0.3): icmp_seq=3 ttl=64 time=0.081 ms

# コンテナ内のDNS設定
$ docker compose exec web cat /etc/resolv.conf
nameserver 127.0.0.11
options ndots:0

$ docker network inspect myapp_default
[
    {
        "Name": "myapp_default",
        "Driver": "bridge",
        "Containers": {
            "a1b2c3...": {
                "Name": "myapp-web-1",
                "IPv4Address": "172.18.0.2/16"
            },
            "d4e5f6...": {
                "Name": "myapp-db-1",
                "IPv4Address": "172.18.0.3/16"
            }
        }
    }
]

# カスタムネットワークを定義するcompose.ymlの基本形
services:
  nginx:
    image: nginx:1.25
    ports:
      - "80:80"
    networks:
      - frontend

  app:
    image: myapp:latest
    networks:
      - frontend
      - backend

  db:
    image: postgres:15
    networks:
      - backend

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge

# nginx-app-dbの3層構成でネットワークを分離する例
services:
  nginx:
    image: nginx:1.25
    ports:
      - "80:80"
    networks:
      - frontend
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro

  app:
    image: myapp:latest
    networks:
      - frontend   # nginxと通信できる
      - backend    # dbと通信できる
    environment:
      - DB_HOST=db

  db:
    image: postgres:15
    networks:
      - backend    # appとのみ通信できる（nginxからは見えない）
    volumes:
      - db_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_PASSWORD=secret

volumes:
  db_data:

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge

# appコンテナからdbへはアクセスできる
$ docker compose exec app ping -c 2 db
PING db (172.19.0.3) 56(84) bytes of data.
64 bytes from db (172.19.0.3): icmp_seq=1 ttl=64 time=0.112 ms
64 bytes from db (172.19.0.3): icmp_seq=2 ttl=64 time=0.089 ms

# nginxコンテナからdbへはアクセスできない（別ネットワーク）
$ docker compose exec nginx ping -c 2 db
ping: db: Name or service not known

services:
  db:
    image: mysql:8.0
    networks:
      backend:
        aliases:
          - mysql        # サービス名"db"に加え"mysql"でもアクセス可能
          - database

# まず手動で共有ネットワークを作成する（1度だけ実行）
$ docker network create shared_monitoring
8f3c9a1b2d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

# 作成確認
$ docker network ls | grep shared_monitoring
8f3c9a1b2d4e   shared_monitoring       bridge    local

# アプリ側のcompose.yml（monitoring networkにもアクセス可能にする）
services:
  app:
    image: myapp:latest
    networks:
      - backend
      - monitoring

networks:
  backend:
    driver: bridge
  monitoring:
    external: true          # Composeの外で管理するネットワーク
    name: shared_monitoring # 実際のネットワーク名を指定

# 監視ツール側のcompose.yml（同じshared_monitoringに参加）
services:
  prometheus:
    image: prom/prometheus:latest
    networks:
      - monitoring

networks:
  monitoring:
    external: true
    name: shared_monitoring

$ docker compose up
network shared_monitoring declared as external, but could not be found

# 対処: 先にdocker network createで作成する
$ docker network create shared_monitoring

# 現在存在するネットワークを確認
$ docker network ls

# 特定ネットワークの詳細（参加コンテナのIPを含む）
$ docker network inspect myapp_frontend

# webからdbへのpingテスト
$ docker compose exec web ping -c 3 db

# DNSが解決できない場合（別ネットワーク）
ping: db: Name or service not known

# IPアドレス直打ちで通るかを確認（DNSだけの問題か切り分ける）
$ docker compose exec web ping -c 3 172.18.0.3

# appからdbの5432ポートが開いているかncで確認
$ docker compose exec app nc -z db 5432
Connection to db (172.19.0.3) 5432 port [tcp/postgresql] succeeded!

# タイムアウトする場合は別ネットワーク・ポート未開放を疑う
$ docker compose exec app nc -z -w 3 db 5432