Docker에서는 컨테이너 간의 통신을 위해 Network를 사용합니다. 일반적으로 컨테이너를 생성할 때 --network 옵션으로 원하는 네트워크를 지정하지만, 이미 실행 중인 컨테이너를 다른 네트워크에 추가로 연결해야 하는 경우도 자주 발생합니다.
예를 들어 Nginx 컨테이너를 Backend Network에 연결하거나, 기존 MySQL 컨테이너를 새롭게 생성한 데이터베이스 전용 네트워크에 연결해야 하는 상황이 있습니다. 컨테이너를 다시 생성하지 않고도 이러한 작업을 수행할 수 있는 명령어가 바로 docker network connect입니다.
Docker Network Connect는 실행 중인 컨테이너를 특정 Docker Network에 연결하는 명령어입니다. 하나의 컨테이너는 여러 개의 Docker Network에 동시에 연결될 수 있기 때문에 운영 환경에서 매우 자주 활용됩니다.
이번 글에서는 Docker Network Connect의 개념부터 기본 사용법, 주요 옵션, 실무 활용 방법까지 자세히 알아보겠습니다.
Docker Network Connect란 무엇인가?
Docker Network Connect는 실행 중인 컨테이너를 기존 Docker Network에 연결하는 명령어입니다.
이미 실행 중인 컨테이너를 중지하거나 다시 생성하지 않아도 새로운 네트워크를 추가할 수 있습니다.
운영 환경에서는 서비스 확장이나 네트워크 구성 변경 시 자주 사용하는 명령어입니다.
Docker Network Connect는 언제 사용하는가?
다음과 같은 상황에서 많이 사용합니다.
- 실행 중인 컨테이너를 새로운 Network에 연결
- 프로젝트 네트워크 변경
- Nginx와 Backend 연결
- MySQL 연결
- Redis 연결
- 서비스 확장
운영 서버에서는 컨테이너를 재생성하지 않고 네트워크를 변경할 수 있다는 점이 가장 큰 장점입니다.
Docker Network Connect 기본 사용법
가장 기본적인 사용 방법입니다.
docker network connect web_network nginx첫 번째에는 연결할 Docker Network를 입력하고 두 번째에는 컨테이너 이름을 입력합니다.
명령이 정상적으로 실행되면 별도의 출력 없이 연결이 완료됩니다.
연결 여부 확인하기
컨테이너가 정상적으로 연결되었는지 확인하려면 다음 명령을 사용합니다.
docker network inspect web_network출력 결과의 Containers 항목에서 해당 컨테이너가 표시되면 정상적으로 연결된 것입니다.
하나의 컨테이너를 여러 Network에 연결하기
Docker에서는 하나의 컨테이너를 여러 네트워크에 동시에 연결할 수 있습니다.
예를 들어 다음과 같이 연결할 수 있습니다.
docker network connect frontend_network nginx
docker network connect backend_network nginx이 경우 Nginx 컨테이너는 두 개의 Network를 모두 사용할 수 있습니다.
이는 Reverse Proxy 서버에서 매우 많이 사용하는 구성입니다.
고정 IP 지정하기
컨테이너를 연결하면서 IP 주소를 직접 지정할 수도 있습니다.
docker network connect \
--ip 172.20.0.100 \
web_network \
nginx특정 서비스가 고정 IP를 사용해야 하는 환경에서 활용됩니다.
Alias 지정하기
네트워크에서 사용할 별칭도 지정할 수 있습니다.
docker network connect \
--alias webserver \
web_network \
nginx같은 Network 안에서는 webserver라는 이름으로도 접근할 수 있습니다.
운영 환경에서는 서비스 이름을 통일하기 위해 Alias를 사용하는 경우가 있습니다.
Docker Network Connect 실무 활용 예제
Docker Network Connect는 실행 중인 컨테이너를 새로운 네트워크에 연결해야 할 때 가장 많이 사용하는 명령어입니다. 특히 서비스 확장이나 네트워크 재구성 작업에서 매우 유용합니다.
실행 중인 컨테이너를 Network에 연결하기
가장 기본적인 사용 방법입니다.
docker network connect web_network nginxNginx 컨테이너가 web_network에 연결됩니다.
연결 여부 확인하기
정상적으로 연결되었는지 확인합니다.
docker network inspect web_network출력 결과의 Containers 항목에 nginx가 표시되면 정상적으로 연결된 것입니다.
하나의 컨테이너를 여러 Network에 연결하기
Docker에서는 하나의 컨테이너를 여러 개의 네트워크에 동시에 연결할 수 있습니다.
docker network connect frontend_network nginx
docker network connect backend_network nginx이 구성은 Reverse Proxy 서버나 API Gateway 환경에서 자주 사용됩니다.
Alias를 지정하여 연결하기
네트워크 안에서 사용할 별칭을 지정할 수 있습니다.
docker network connect \
--alias api-server \
backend_network \
spring같은 네트워크의 다른 컨테이너에서는 api-server라는 이름으로 접근할 수 있습니다.
고정 IP를 지정하여 연결하기
특정 IP를 사용해야 하는 경우에는 다음과 같이 설정합니다.
docker network connect \
--ip 172.20.0.50 \
backend_network \
mysql고정 IP가 필요한 레거시 시스템이나 특정 서비스에서 활용됩니다.
연결된 Network 확인하기
현재 컨테이너가 어떤 네트워크에 연결되어 있는지 확인합니다.
docker inspect nginxNetworkSettings 항목에서 연결된 모든 Docker Network를 확인할 수 있습니다.
Linux 서버 문제 해결
운영 중인 Docker 서버에서 Nginx 컨테이너는 정상적으로 실행되고 있었지만 Backend API와 통신하지 못하는 문제가 발생했습니다.
확인 결과 Nginx는 frontend_network에만 연결되어 있었고 Backend API는 backend_network에만 연결되어 있었습니다.
관리자는 Nginx를 Backend Network에도 연결했습니다.
docker network connect backend_network nginx연결 후 네트워크 정보를 확인했습니다.
docker network inspect backend_networkNginx 컨테이너가 목록에 추가된 것을 확인한 뒤 서비스 테스트를 진행했고, API 호출이 정상적으로 이루어졌습니다.
이처럼 Docker Network Connect는 컨테이너를 재시작하지 않고도 네트워크 구성을 변경할 수 있기 때문에 운영 환경에서 매우 유용한 명령어입니다.
Docker Network Connect 사용 시 주의사항
Docker Network Connect를 사용할 때는 다음 사항을 알아두면 좋습니다.
첫 번째는 연결하려는 Docker Network가 이미 존재해야 한다는 점입니다.
존재하지 않는 네트워크를 지정하면 오류가 발생합니다.
두 번째는 동일한 네트워크에 이미 연결된 컨테이너는 다시 연결할 수 없습니다.
중복 연결을 시도하면 오류 메시지가 출력됩니다.
세 번째는 고정 IP를 지정할 경우 다른 컨테이너와 IP가 중복되지 않도록 주의해야 합니다.
네 번째는 서비스 간 통신이 필요한 경우 관련 컨테이너를 동일한 사용자 정의 Bridge Network에 연결하는 것이 가장 권장되는 방법입니다.
Best Practice
Docker Network Connect를 사용할 때는 다음과 같은 방법을 추천합니다.
- 프로젝트별 사용자 정의 Network를 사용합니다.
- 컨테이너 이름 기반 통신을 적극 활용합니다.
- 필요한 경우에만 고정 IP를 사용합니다.
- Network 연결 후
docker network inspect로 확인합니다. - 서비스 역할에 맞게 여러 Network를 구성합니다.
- 불필요한 Network 연결은 최소화하여 보안을 강화합니다.
이러한 방법을 적용하면 Docker 네트워크를 더욱 안정적이고 효율적으로 운영할 수 있습니다.
자주 묻는 질문
실행 중인 컨테이너도 Network를 추가할 수 있나요?
네.
docker network connect를 사용하면 컨테이너를 중지하지 않고도 새로운 네트워크를 추가할 수 있습니다.
하나의 컨테이너를 여러 Network에 연결할 수 있나요?
가능합니다.
Docker는 하나의 컨테이너를 여러 Docker Network에 동시에 연결할 수 있습니다.
Alias는 언제 사용하나요?
같은 네트워크 안에서 서비스 이름을 통일하거나 접근 이름을 단순하게 만들고 싶을 때 사용합니다.
Network 연결 후 재시작해야 하나요?
아닙니다.
정상적으로 연결되면 별도의 재시작 없이 즉시 사용할 수 있습니다.
마무리
Docker Network Connect는 실행 중인 컨테이너를 새로운 Docker Network에 연결하는 핵심 관리 명령어입니다.
컨테이너를 재생성하거나 중지하지 않고도 네트워크를 확장할 수 있어 운영 환경에서 매우 유용하며, 특히 마이크로서비스 환경이나 Reverse Proxy 구성에서 자주 활용됩니다.
docker network inspect와 함께 사용하면 컨테이너의 연결 상태를 쉽게 확인할 수 있으므로 Docker 네트워크 관리에 반드시 익혀두어야 하는 명령어입니다.