Docker 컨테이너 네트워킹 실전: Web 컨테이너와 데이터베이스 컨테이너를 올바르게 연결하는 방법

금요일 오후 3시, 로컬 개발 환경을 컨테이너화하면서 꽤 뿌듯해하고 있었습니다. MySQL 컨테이너도 성공적으로 시작했고 Node.js 애플리케이션 컨테이너도 실행 중이었으니, 이제 둘을 연결하는 마지막 단계만 남아 있었습니다. 그런데 브라우저에서 페이지를 새로 고치자 곧바로 500 오류가 발생했고 로그에는 “Connection refused”가 잔뜩 찍혔습니다.

처음에는 정말 당황했습니다. 분명 두 컨테이너가 모두 실행 중이었기 때문입니다. 그래서 MySQL 컨테이너 이름으로 ping을 보내 봤지만 결과는 “unknown host”였습니다. 그렇다면 IP 주소로 시도해 보자는 생각에 연결했더니 뜻밖에도 성공했습니다. 애플리케이션도 데이터베이스에 연결되었습니다. 안도의 한숨을 쉬고 코드를 커밋한 뒤 컴퓨터를 끄고 퇴근했습니다.

월요일에 돌아오자 문제가 다시 발생했습니다. 확인해 보니 MySQL 컨테이너를 재시작한 뒤 IP가 172.17.0.2에서 172.17.0.3으로 바뀌어 있었습니다. 컨테이너를 재시작할 때마다 설정 파일을 바꿔야 하는 건지 정말 답답했습니다.

비슷한 문제를 겪은 적이 있다면 이 글이 도움이 될 것입니다. 저는 오후 내내 Docker의 네트워크 구조를 살펴본 끝에 컨테이너를 서로 연결하는 올바른 방법을 이해했습니다. 이제 다음 내용을 함께 살펴보겠습니다.

• 컨테이너 이름으로 ping이 되지 않는 근본 원인
• Docker 기본 네트워크의 한계
• 사용자 정의 네트워크가 이 문제를 해결하는 방식
• 컨테이너끼리 이름으로 접근하게 만드는 전체 실습 과정
• 몇 가지 고급 팁과 모범 사례

컨테이너 이름으로 ping이 되지 않는 이유

Docker 기본 네트워크의 한계

문제의 원인은 Docker의 기본 네트워크 설정에 있습니다. 별도로 네트워크를 지정하지 않고 컨테이너를 시작하면 Docker는 컨테이너를 기본 bridge 네트워크, 즉 docker0 브리지에 자동으로 연결합니다.

이 기본 네트워크에는 큰 제약이 하나 있습니다. IP 주소를 통한 통신만 지원하고 컨테이너 이름 해석은 지원하지 않습니다.

무슨 뜻일까요? 기본 네트워크에서는 다음과 같습니다.

• ✅ IP로 다른 컨테이너에 접근할 수 있습니다(예: ping 172.17.0.2).
• ❌ 컨테이너 이름으로는 접근할 수 없습니다(예: ping mysql-container는 실패합니다).

왜 이런 일이 생길까요? 기본 네트워크에는 내장 DNS 서비스가 없기 때문입니다. 전화번호부가 없는 휴대전화와 비슷합니다. 상대방의 번호(IP)는 기억할 수 있지만 이름(컨테이너 이름)으로는 찾을 수 없습니다.

더 큰 문제는 컨테이너를 재시작할 때마다 Docker가 IP 주소를 다시 할당한다는 점입니다. 오늘은 172.17.0.2로 MySQL에 연결했더라도 내일 재시작하면 172.17.0.3으로 바뀔 수 있고, 그러면 애플리케이션 설정의 IP 주소는 무효가 됩니다.

명령어로 직접 확인해 보았습니다.

# MySQL 컨테이너 시작(기본 네트워크 사용)
docker run -d --name mysql-demo \
  -e MYSQL_ROOT_PASSWORD=123456 \
  mysql:8.0

# 네트워크 테스트용 busybox 컨테이너 시작
docker run -it --name test-box busybox sh

# test-box 컨테이너 안에서 MySQL 컨테이너 이름으로 ping 시도
/ # ping mysql-demo
ping: bad address 'mysql-demo'  # ← 이름 해석 실패

# MySQL 컨테이너의 IP 확인
docker inspect mysql-demo | grep IPAddress
# "IPAddress": "172.17.0.2"

# IP로는 ping 성공
/ # ping 172.17.0.2
PING 172.17.0.2 (172.17.0.2): 56 data bytes
64 bytes from 172.17.0.2: seq=0 ttl=64 time=0.123 ms

보시다시피 컨테이너 이름으로는 ping이 되지 않고 IP로만 연결됩니다.

--link 매개변수는 더 이상 권장되지 않습니다

오래된 튜토리얼에서 --link 매개변수를 본 적이 있을 수 있습니다. Docker가 초기에 제공했던 해결 방법이며 사용법은 다음과 같습니다.

docker run --link mysql-demo:mysql -d my-app

이렇게 하면 my-app 컨테이너가 “mysql”이라는 이름으로 mysql-demo 컨테이너에 접근할 수 있습니다. 하지만 Docker는 공식적으로 --link 사용을 더 이상 권장하지 않으며 이후 버전에서는 이 기능을 제거할 예정입니다.

권장되지 않는 이유는 주로 다음과 같습니다.

1. 단방향 연결: my-app만 mysql에 접근할 수 있고, 반대로 mysql은 my-app에 접근할 수 없습니다.
2. 어려운 유지 관리: 컨테이너가 많아지면 --link 설정이 매우 복잡해집니다.
3. 제한된 기능: 여러 컨테이너를 유연하게 관리하는 네트워크 구성을 지원하지 않습니다.

아직 --link를 사용하고 있다면 이제 새로운 방식으로 전환할 때입니다.

사용자 정의 네트워크: 컨테이너를 올바르게 연결하는 방법

사용자 정의 네트워크의 장점

Docker는 1.12 버전부터 사용자 정의 네트워크를 만들 수 있는 docker network 명령을 제공합니다. 이것이 Docker에서 공식적으로 권장하는 컨테이너 연결 방식입니다.

사용자 정의 bridge 네트워크는 기본 네트워크보다 다음과 같은 장점이 있습니다.

1. 자동 DNS 해석: Docker는 사용자 정의 네트워크에서 내장 DNS 서버를 실행하고 컨테이너 이름을 해당 IP 주소로 자동 해석합니다. Docker가 이 네트워크에 일종의 “주소록” 기능을 추가한다고 이해하면 됩니다.

2. 네트워크 격리: 서로 다른 사용자 정의 네트워크에 있는 컨테이너는 기본적으로 격리되어 상호 접근할 수 없습니다. 따라서 프론트엔드 서비스, 백엔드 서비스, 데이터베이스를 각각 다른 네트워크에 배치해 안전하게 격리할 수 있습니다.

3. 향상된 유지 관리성: 컨테이너 재시작 후 IP가 바뀌어도 상관없습니다. 컨테이너 이름을 사용하면 DNS가 해석 레코드를 자동으로 갱신하기 때문입니다.

4. 다중 네트워크 지원: 하나의 컨테이너를 여러 네트워크에 동시에 연결해 더 복잡한 네트워크 토폴로지를 구성할 수 있습니다.

솔직히 저도 처음에는 Docker 네트워크가 매우 복잡하다고 생각했습니다. 하지만 이 네 가지를 이해하고 나니 한순간에 모든 것이 명확해졌습니다.

Alibaba Cloud - 개발자 클라우드 1순위, Lighthouse 서버 15% 할인

15% 할인 받기 →광고

사용자 정의 네트워크 생성

사용자 정의 네트워크를 만드는 명령은 매우 간단합니다.

# 가장 간단한 방법: 네트워크 이름만 지정
docker network create my-app-net

# 전체 매개변수 버전
docker network create \
  --driver bridge \         # 네트워크 드라이버 유형, 기본값은 bridge
  --subnet 172.20.0.0/16 \  # 사용자 정의 IP 대역(선택 사항)
  --gateway 172.20.0.1 \    # 사용자 정의 게이트웨이(선택 사항)
  my-app-net                # 네트워크 이름

대부분의 상황에서는 첫 번째의 간단한 방법이면 충분합니다. Docker가 충돌하지 않는 IP 대역을 자동으로 할당합니다.

생성한 뒤에는 다음 명령으로 네트워크의 상세 정보를 확인할 수 있습니다.

docker network inspect my-app-net

IP 대역, 게이트웨이, 연결된 컨테이너 등 이 네트워크의 설정 정보가 표시됩니다.

컨테이너를 사용자 정의 네트워크에 연결하기

컨테이너를 사용자 정의 네트워크에 연결하는 방법은 두 가지입니다.

방법 1: 컨테이너 시작 시 지정(권장)

docker run -d \
  --name mysql-demo \
  --network my-app-net \  # ← 핵심 매개변수
  -e MYSQL_ROOT_PASSWORD=123456 \
  mysql:8.0

방법 2: 실행 중인 컨테이너를 네트워크에 연결

# 컨테이너가 이미 실행 중이라고 가정
docker network connect my-app-net existing-container

첫 번째 방법은 한 번에 설정을 끝낼 수 있어 더 권장됩니다. 두 번째 방법은 기존 컨테이너를 새 네트워크로 옮기고 싶을 때 적합합니다.

실전 예제: Web 애플리케이션에서 MySQL 데이터베이스에 접근하기

이제 이론은 충분히 살펴봤으니 직접 실습해 보겠습니다. 실제 시나리오를 통해 Node.js 애플리케이션 컨테이너를 구성하고 MySQL 데이터베이스 컨테이너에 연결해 보겠습니다.

시나리오 설정

구현하려는 목표는 다음과 같습니다.

• MySQL 컨테이너의 이름은 mysql-server이며 사용자 정의 네트워크에서 실행됩니다.
• Node.js 애플리케이션 컨테이너의 이름은 node-app이며 같은 네트워크에서 실행됩니다.
• 애플리케이션은 IP가 아닌 컨테이너 이름 “mysql-server”로 데이터베이스에 연결합니다.

전체 구현 단계

1단계: 사용자 정의 네트워크 생성

docker network create my-app-net

실행하면 다음과 같은 네트워크 ID 문자열이 출력됩니다.

a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890

이 문자열이 나오면 네트워크 생성에 성공한 것입니다.

2단계: MySQL 컨테이너를 시작하고 네트워크에 연결

docker run -d \
  --name mysql-server \
  --network my-app-net \
  -e MYSQL_ROOT_PASSWORD=my-secret-pw \
  -e MYSQL_DATABASE=myapp_db \
  mysql:8.0

매개변수 설명은 다음과 같습니다.

• --name mysql-server: 컨테이너 이름을 지정합니다. 이 이름이 이후 데이터베이스에 접근할 때 사용하는 host가 됩니다.
• --network my-app-net: 앞에서 만든 네트워크에 연결합니다.
• -e MYSQL_ROOT_PASSWORD: root 비밀번호를 설정합니다.
• -e MYSQL_DATABASE: 초기 데이터베이스를 생성합니다.

3단계: 애플리케이션 컨테이너를 시작하고 네트워크에 연결

여기서는 간단한 Node.js 예제를 사용합니다. 필요에 맞게 조정할 수 있습니다.

docker run -d \
  --name node-app \
  --network my-app-net \
  -p 3000:3000 \
  -e DB_HOST=mysql-server \
  -e DB_USER=root \
  -e DB_PASSWORD=my-secret-pw \
  -e DB_NAME=myapp_db \
  my-node-app:latest

DB_HOST=mysql-server에 주목하세요. IP 주소가 아니라 컨테이너 이름을 사용합니다.

4단계: 애플리케이션 코드에서 컨테이너 이름으로 데이터베이스에 연결

Node.js 코드 예시는 다음과 같습니다.

const mysql = require('mysql2');

// 환경 변수로 데이터베이스 연결 설정
const connection = mysql.createConnection({
  host: process.env.DB_HOST,      // 값은 'mysql-server'(컨테이너 이름)
  user: process.env.DB_USER,      // 값은 'root'
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME
});

connection.connect((err) => {
  if (err) {
    console.error('데이터베이스 연결 실패:', err);
    return;
  }
  console.log('MySQL 데이터베이스 연결 성공!');
});

핵심은 host에 컨테이너 이름인 mysql-server를 사용한다는 점입니다. Docker의 DNS가 이 이름을 MySQL 컨테이너의 현재 IP로 자동 해석합니다.

5단계: 연결 확인

node-app 컨테이너에 들어가 네트워크 연결을 직접 테스트할 수 있습니다.

# 애플리케이션 컨테이너 접속
docker exec -it node-app sh

# MySQL 컨테이너 이름으로 ping
/ # ping mysql-server
PING mysql-server (172.20.0.2): 56 data bytes
64 bytes from 172.20.0.2: seq=0 ttl=64 time=0.089 ms
64 bytes from 172.20.0.2: seq=1 ttl=64 time=0.096 ms

성공했습니다. 컨테이너 이름이 정상적으로 해석되고 ping도 통합니다.

nslookup 명령으로 DNS 해석 결과를 확인할 수도 있습니다.

/ # nslookup mysql-server
Server:    127.0.0.11  # ← Docker 내장 DNS 서버
Address:   127.0.0.11:53

Name:      mysql-server
Address:   172.20.0.2  # ← MySQL 컨테이너 IP로 자동 해석

Docker는 사용자 정의 네트워크에서 DNS 서버(127.0.0.11)를 실행해 컨테이너 이름을 해석합니다.

KiloClaw - 기업용 매니지드 OpenClaw, AI Agent 오케스트레이션 및 스마트 라우팅

시작하기 →광고

이제 MySQL 컨테이너를 재시작해 IP가 바뀌어도 DNS가 해석 레코드를 자동 갱신하므로 애플리케이션에는 영향을 주지 않습니다.

문제 해결 팁

문제가 발생했을 때 자주 사용하는 점검 명령은 다음과 같습니다.

1. 네트워크 상세 정보 확인

docker network inspect my-app-net

다음을 포함한 상세 정보가 JSON 형식으로 출력됩니다.

• 네트워크의 IP 대역과 게이트웨이
• 연결된 컨테이너 목록
• 각 컨테이너에 이 네트워크에서 할당된 IP

2. 컨테이너의 네트워크 설정 확인

docker inspect mysql-server | grep -A 20 Networks

컨테이너가 어떤 네트워크에 연결되어 있는지, 각 네트워크의 IP가 무엇인지 확인할 수 있습니다.

3. 컨테이너 로그 확인

docker logs node-app
docker logs mysql-server

로그에는 일반적으로 연결 오류의 상세 정보가 남습니다.

자주 발생하는 문제 점검표

고급 팁과 모범 사례

다중 네트워크 구성: 프론트엔드와 백엔드 분리

실제 프로젝트에서는 더 복잡한 네트워크 토폴로지가 필요할 수 있습니다. 예를 들어 프론트엔드, 백엔드, 데이터베이스를 서로 다른 네트워크 계층에 배치하고 싶을 수 있습니다.

# 두 개의 네트워크 생성
docker network create frontend-net  # 프론트엔드 네트워크
docker network create backend-net   # 백엔드 네트워크

# 프론트엔드 컨테이너는 frontend-net에만 연결
docker run -d --name nginx \
  --network frontend-net \
  -p 80:80 \
  nginx:latest

# API 백엔드는 두 네트워크에 모두 연결(프론트엔드와 백엔드 모두 접근해야 함)
docker run -d --name api-server \
  --network frontend-net \
  my-api:latest

docker network connect backend-net api-server

# 데이터베이스는 backend-net에만 연결(프론트엔드에서 접근할 수 없어 더 안전함)
docker run -d --name postgres \
  --network backend-net \
  -e POSTGRES_PASSWORD=secret \
  postgres:14

이 구조의 장점은 무엇일까요?

• 프론트엔드의 nginx 컨테이너는 api-server에 접근할 수 있지만 데이터베이스에는 접근할 수 없습니다.
• api-server는 데이터베이스에 접근할 수 있습니다.
• 데이터베이스는 완전히 격리되어 백엔드만 접근할 수 있으므로 더 안전합니다.

저희 회사 프로젝트도 이런 방식으로 배포하고 있으며 보안성이 상당히 향상되었습니다.

Docker Compose로 관리 간소화

애플리케이션에 컨테이너가 많다면 수동 관리가 번거롭습니다. 이럴 때 Docker Compose가 유용합니다.

docker-compose.yml 파일을 만듭니다.

version: '3.8'

services:
  # MySQL 데이터베이스 서비스
  mysql:
    image: mysql:8.0
    container_name: mysql-server
    environment:
      MYSQL_ROOT_PASSWORD: my-secret-pw
      MYSQL_DATABASE: myapp_db
    networks:
      - app-network
    volumes:
      - mysql-data:/var/lib/mysql

  # Node.js 애플리케이션 서비스
  app:
    image: my-node-app:latest
    container_name: node-app
    ports:
      - "3000:3000"
    environment:
      DB_HOST: mysql  # ← container_name이 아니라 service 이름 사용
      DB_USER: root
      DB_PASSWORD: my-secret-pw
      DB_NAME: myapp_db
    networks:
      - app-network
    depends_on:
      - mysql

# 네트워크 정의
networks:
  app-network:
    driver: bridge

# 데이터 볼륨 정의
volumes:
  mysql-data:

그런 다음 명령 하나로 모든 서비스를 시작합니다.

docker-compose up -d

Docker Compose는 다음 작업을 자동으로 처리합니다.

• app-network 네트워크 생성
• 모든 컨테이너를 시작하고 네트워크에 연결
• 컨테이너 간 DNS 해석 설정
• depends_on에 지정된 순서로 시작(mysql을 먼저 시작하고 app 시작)

중지와 정리도 간단합니다.

# 모든 서비스 중지
docker-compose down

# 서비스 중지 및 데이터 볼륨 삭제
docker-compose down -v

솔직히 지금은 컨테이너를 수동으로 관리하는 일이 거의 없습니다. 모두 Docker Compose로 관리하니 훨씬 효율적입니다.

기타 네트워크 모드 소개

Docker는 bridge 외에도 상황에 따라 사용할 수 있는 여러 네트워크 모드를 지원합니다.

대부분의 경우 사용자 정의 bridge 네트워크면 충분합니다. host 모드는 고빈도 거래 시스템처럼 네트워크 성능 요구가 매우 높은 상황에 적합합니다. overlay 모드는 Swarm과 K8s 같은 오케스트레이션 도구의 기반 기술이며 일반적으로 직접 설정할 필요는 없습니다.

자주 묻는 질문

Q1: IP로는 연결되는데 컨테이너 이름으로는 연결되지 않는 이유는 무엇인가요?

A: 컨테이너가 기본 bridge 네트워크(docker0)에 있기 때문입니다. 기본 네트워크에는 DNS 서비스가 없어 컨테이너 이름 해석을 지원하지 않습니다. 사용자 정의 네트워크를 생성하고 컨테이너를 연결하면 해결됩니다.

Q2: --link를 아직 사용할 수 있나요?

A: 현재도 사용할 수는 있지만 Docker는 공식적으로 더 이상 권장하지 않으며 향후 버전에서 제거할 예정입니다. 기능이 더 강력하고 향후 방향에도 부합하는 사용자 정의 네트워크로 가능한 한 빨리 전환하기를 권합니다.

Vultr - 고성능 NVMe 클라우드 서버, 전 세계 32개 노드, Docker 원클릭 배포

요금 보기 →광고

Q3: 사용자 정의 네트워크가 성능에 영향을 주나요?

A: 영향은 거의 없습니다. 사용자 정의 네트워크와 기본 네트워크는 모두 bridge 모드이고 기반 구현도 같습니다. DNS 해석 기능이 추가될 뿐이므로 성능 차이는 무시할 수 있는 수준입니다.

Q4: 컨테이너가 외부 네트워크에 접근하게 하려면 어떻게 해야 하나요?

A: 기본적으로 bridge 네트워크의 컨테이너는 NAT를 통해 외부 네트워크에 접근할 수 있습니다. 접근할 수 없다면 Docker의 iptables 규칙이나 호스트의 네트워크 설정을 확인하세요.

Q5: 기존 컨테이너를 사용자 정의 네트워크로 옮기려면 어떻게 해야 하나요?

A: 두 단계로 진행합니다.

# 1. 컨테이너를 새 네트워크에 연결
docker network connect my-app-net old-container

# 2. 기본 네트워크 연결 해제(선택 사항)
docker network disconnect bridge old-container

다만 컨테이너를 다시 생성하면서 --network 매개변수로 사용자 정의 네트워크에 바로 연결하는 방법을 더 권장합니다.

Q6: 컨테이너 이름에 대문자를 사용할 수 있나요?

A: 사용할 수 있지만 권장하지 않습니다. DNS 규격에서는 소문자, 숫자, 하이픈 사용을 권장합니다. 이 규칙을 따르면 호환성이 더 좋고 문제도 줄어듭니다.

Q7: 컨테이너 하나를 여러 네트워크에 동시에 연결할 수 있나요?

A: 가능합니다. 이것이 바로 사용자 정의 네트워크의 강점입니다. docker network connect로 컨테이너를 여러 네트워크에 연결해 복잡한 네트워크 토폴로지를 구현할 수 있습니다.

정리

핵심 내용을 다시 살펴보겠습니다.

1단계: 문제의 원인 이해

• Docker 기본 네트워크는 컨테이너 이름 해석을 지원하지 않으며 IP만 사용할 수 있습니다.
• 컨테이너 재시작 후 IP가 바뀌면 연결이 끊어집니다.
• --link 매개변수는 더 이상 권장되지 않으므로 사용하지 마세요.

2단계: 사용자 정의 네트워크 생성

docker network create my-app-net

3단계: 컨테이너를 네트워크에 연결하고 컨테이너 이름으로 통신

# 컨테이너 시작 시 네트워크 지정
docker run -d --name mysql-server --network my-app-net mysql:8.0

# 애플리케이션에서 컨테이너 이름으로 연결
host: 'mysql-server'  // IP가 아니라 컨테이너 이름

이 방식은 간단할 뿐 아니라 Docker가 공식적으로 권장하는 모범 사례입니다. 컨테이너화된 애플리케이션을 더 안정적이고 쉽게 유지 관리할 수 있습니다.

마이크로서비스나 다중 컨테이너 프로젝트를 진행하고 있다면 다음을 적극 권합니다.

1. 지금 바로 적용하기: 기존 프로젝트를 사용자 정의 네트워크 방식으로 전환해 IP 주소 하드코딩에서 벗어나세요.
2. Compose 사용해 보기: 컨테이너가 3개 이상이라면 Docker Compose로 더 간편하게 관리하세요.
3. 더 깊이 학습하기: 클라우드 네이티브의 기반인 overlay 네트워크와 Kubernetes 네트워크 모델을 알아보세요.

컨테이너 네트워크에는 분명 학습 곡선이 있습니다. 하지만 한번 익히고 나면 Docker가 훨씬 더 편리해집니다. 이제 직접 해보고 싶지 않으신가요? 터미널을 열고 첫 번째 사용자 정의 네트워크를 만들어 보세요.

궁금한 점은 댓글로 남겨 주세요. 가능한 한 답변드리겠습니다.