Docker Network 동작: DB 연결시 localhost 대신 서비스 이름을 사용해야 하는 이유

spring.datasource.url=jdbc:mysql://my-db:3306/mydb
spring.datasource.username=root
spring.datasource.password=pwd123
spring.datasource.driver-class-name=cohttp://m.mysql.cj.jdbc.Driver
spring.jpa.hibernate.ddl-auto=update

 

DB 연결 문자열에서 흔히 볼 수 있는 패턴 중 하나는 localhost:3306과 같은 형태다. 그러나 Docker 환경으로 전환할 때 이 패턴은 기대와 같이 동작하지 않으며, localhost 대신 해당 서비스 이름을 사용해야 한다. 이 글에서 그 이유를 Docker의 네트워킹 원리를 통해 알아보려 한다.

 

로컬 개발 환경에서의 연결

로컬 개발 환경에서 localhost는 자신의 컴퓨터를 가리키는 특별한 호스트명이다. 이는 IP 주소 127.0.0.1에 매핑되며, 루프백 인터페이스를 통해 동작한다.

jdbc:mysql://localhost:3306/mysql

jdbc:mysql://127.0.0.1:3306/mysql

위 두 연결 문자열은 기능적으로 동일하며, 다음과 같은 과정으로 처리된다.

1. OS의 호스트 파일(/etc/hosts) 또는 DNS 리졸버가 localhost를 127.0.0.1로 해석
2. 루프백 인터페이스를 통해 로컬 컴퓨터 내에서 패킷 전송
3. 네트워크 카드(NIC)를 거치지 않고 내부적으로 직접 통신
4. MySQL 서버가 3306 포트에서 대기 중이면 연결 성공

MySQL 서버는 기본적으로 사용자에게 호스트 기반 접근 권한을 부여하는데, root 사용자는 일반적으로 localhost에서만 접속이 가능하도록 설정된다. 이로 인해 로컬 개발 환경에서는 localhost 또는 127.0.0.1을 통한 접속은 허용되지만, 다른 IP 주소를 통한 접속은 별도의 권한 설정 없이는 불가능하다.

 

Docker 환경의 네트워크 구조

Docker는 리눅스 커널의 네임스페이스(namespace) 기술을 활용해 각 컨테이너에 독립적인 네트워크 환경을 제공한다. 이 때문에 로컬 개발 환경과 다른 설정이 필요해진다.

1. 컨테이너 격리와 네트워크 네임스페이스

Docker는 리눅스 커널의 네임스페이스(namespace)를 사용해 각 컨테이너에 독립적인 네트워크 스택을 제공한다.

• 각 컨테이너는 자체 네트워크 인터페이스, 라우팅 테이블, IP 주소를 가진다.
• 컨테이너 내부에서 localhost는 항상 해당 컨테이너 자신만을 가리킨다.
• 즉, 다른 컨테이너나 호스트 머신을 가리키지 않는다.

때문에 Docker 환경에서 localhost:3306으로 MySQL에 연결할 수 없는 이유이다. 애플리케이션 컨테이너에서 해당 주소로 연결을 시도하면, 실제로는 자기 자신의 3306 포트에 연결을 시도하게 된다. 그러나 우리의 의도는 애플리케이션 컨테이너 내부의 3306 포트가 아닌 MySQL 컨테이너 내 3306 포트로의 연결이다.  따라서 애플리케이션은 MySQL연결에 실패하게 된다. 

 

2. Docker의 내장 DNS 해석 시스템

Docker는 내장 DNS 서버를 사용하여 컨테이너 이름과 서비스 이름을 IP 주소로 변환한다.

애플리케이션 컨테이너 → "my-db" 요청 → Docker DNS → my-db 컨테이너의 IP(ex: 172.18.0.3)

 

• 모든 컨테이너는 Docker DNS 서버를 사용하도록 /etc/resolv.conf가 자동 구성된다.
• 내장 DNS는 서비스 이름을 컨테이너 IP로 변환하는 레지스트리를 유지한다.
• IP 주소가 바뀌어도(ex: 컨테이너 재시작) DNS 해석은 자동으로 업데이트된다.

3. Docker Compose의 자동 네트워크 구성

Docker Compose를 사용하면 자동으로 모든 서비스를 위한 기본 브릿지 네트워크가 생성된다.

• 각 컨테이너에 내부 IP 주소가 할당된다.
• 모든 컨테이너는 이 네트워크에 연결되어 서로 통신할 수 있다.
• Docker Compose는 내장 DNS 서버를 구성하여 서비스 이름을 컨테이너 IP 주소로 자동 해석한다.

실제 작동 방식 예시

Docker Compose 환경에서의 설정에 따라 데이터베이스 연결이 실제로 어떻게 작동하는지 살펴보자.

서비스 이름(my-db)을 사용한 경우

1. my-server 컨테이너가 my-db:3306에 연결 시도
2. Docker의 내장 DNS가 my-db를 실제 IP 주소(ex: 172.18.0.3)로 변환
3. 연결이 172.18.0.3:3306으로 라우팅 됨
4. 이 주소는 MySQL 컨테이너의 실제 IP와 포트를 가리킴

localhost를 사용한 경우 - 실패

• 연결이 127.0.0.1:3306(자기 자신)으로 시도됨
• my-server 컨테이너에는 MySQL이 실행되고 있지 않으므로 연결 실패

 

정리

Docker 환경에서 MySQL과 같은 데이터베이스에 연결할 때는 localhost 대신 서비스 이름을 사용해야 한다. 이는 Docker의 네트워크 격리와 내장 DNS 시스템 때문이다. 각 컨테이너는 독립된 네트워크 환경을 가지며, localhost는 항상 컨테이너 자신을 가리키기 때문에 다른 컨테이너에 접근하려면 서비스 이름을 사용해야 한다.