Docker Compose에서 네트워크 정의·관리
Docker Compose에서 네트워크 정의·관리 (Networks)
Compose의 networks 최상위 요소는 서비스들이 서로 통신할 수 있게 해주는 이름 있는 네트워크를 구성해요. 기본 네트워크와 사용자 지정 네트워크, 각종 속성을 설명해요.
출처: 문서
본문
네트워크는 서비스들이 서로 통신할 수 있게 해요. 기본적으로 Compose는 앱에 대해 단일 네트워크를 설정해요. 서비스의 각 컨테이너는 기본 네트워크에 참여하고 그 네트워크의 다른 컨테이너에게 도달 가능하며, 서비스 이름으로 발견 가능해요. 최상위 networks 요소는 여러 서비스에서 재사용할 수 있는 이름 있는 네트워크를 구성할 수 있게 해요.
여러 서비스에서 네트워크를 사용하려면 services 최상위 요소 안의 networks 속성으로 각 서비스의 접근을 명시적으로 부여해야 해요. networks 최상위 요소는 더 세분화된 제어를 제공하는 추가 문법이 있어요.
예시
기본 예시 (Basic example)
다음 예제에서 런타임에 front-tier와 back-tier 네트워크가 생성되고 frontend 서비스가 front-tier와 back-tier 네트워크에 연결돼요.
services:
frontend:
image: example/webapp
networks:
- front-tier
- back-tier
networks:
front-tier:
back-tier:
고급 예시 (Advanced example)
services:
proxy:
build: ./proxy
networks:
- frontend
app:
build: ./app
networks:
- frontend
- backend
db:
image: postgres:18
networks:
- backend
networks:
frontend:
# 드라이버 옵션 지정
driver: bridge
driver_opts:
com.docker.network.bridge.host_binding_ipv4: "127.0.0.1"
backend:
# 커스텀 드라이버 사용
driver: custom-driver
이 예제는 두 개의 커스텀 네트워크를 정의하는 Compose 파일을 보여줘요. proxy 서비스는 공통 네트워크를 공유하지 않으므로 db 서비스와 격리돼요. 오직 app만 두 서비스와 통신할 수 있어요.
기본 네트워크 (The default network)
Compose 파일이 명시적 네트워크를 선언하지 않으면 Compose는 암시적 기본 네트워크를 사용해요. 명시적 networks 선언이 없는 서비스는 Compose가 이 기본 네트워크에 연결해요:
services:
some-service:
image: foo
이 예제는 실제로 다음과 동등해요:
services:
some-service:
image: foo
networks:
default: {}
networks:
default: {}
명시적 선언으로 기본 네트워크를 커스터마이징할 수 있어요:
networks:
default:
name: a_network # 커스텀 이름 사용
driver_opts: # 네트워크 생성을 위한 옵션을 드라이버에 전달
com.docker.network.bridge.host_binding_ipv4: 127.0.0.1
옵션은 Docker Engine 문서를 참고해요.
속성 (Attributes)
attachable
attachable이 true로 설정되면 standalone 컨테이너도 서비스 외에 이 네트워크에 붙을 수 있어야 해요. standalone 컨테이너가 네트워크에 붙으면 서비스 및 같은 네트워크에 붙은 다른 standalone 컨테이너와 통신할 수 있어요.
networks:
mynet1:
driver: overlay
attachable: true
driver
driver는 이 네트워크에 어떤 드라이버를 사용할지 지정해요. 드라이버가 플랫폼에서 사용 불가능하면 Compose는 오류를 반환해요.
networks:
db-data:
driver: bridge
드라이버와 사용 가능한 옵션에 대한 자세한 내용은 Network drivers 문서를 참고해요.
driver_opts
driver_opts는 드라이버에 전달할 키-값 쌍 옵션 목록을 지정해요. 이 옵션들은 드라이버에 의존적이에요.
networks:
frontend:
driver: bridge
driver_opts:
com.docker.network.bridge.host_binding_ipv4: "127.0.0.1"
자세한 내용은 network drivers 문서를 참고해요.
enable_ipv4
요구 사항: Docker Compose 2.33.1 이상
enable_ipv4로 IPv4 주소 할당을 비활성화할 수 있어요.
networks:
ip6net:
enable_ipv4: false
enable_ipv6: true
enable_ipv6
enable_ipv6는 IPv6 주소 할당을 활성화해요.
networks:
ip6net:
enable_ipv6: true
external
true로 설정하면:
external은 이 네트워크의 라이프사이클이 애플리케이션 밖에서 유지됨을 지정해요. Compose는 이 네트워크를 만들려 시도하지 않고, 존재하지 않으면 오류를 반환해요.name을 제외한 모든 다른 속성은 무관해요. Compose가 다른 속성을 감지하면 Compose 파일을 무효로 거부해요.
다음 예제에서 proxy는 외부 세계로의 게이트웨이예요. Compose는 네트워크를 만들려 시도하는 대신 플랫폼에서 outside라는 기존 네트워크를 조회하고 proxy 서비스의 컨테이너를 연결해요.
services:
proxy:
image: example/proxy
networks:
- outside
- default
app:
image: example/app
networks:
- default
networks:
outside:
external: true
ipam
ipam은 커스텀 IPAM 구성을 지정해요. 각각 선택 사항인 여러 속성을 가진 객체예요:
driver: 기본 대신 커스텀 IPAM 드라이버.config: 다음을 각각 포함하는 0개 이상의 구성 요소 목록:subnet: 네트워크 세그먼트를 나타내는 CIDR 형식 서브넷ip_range: 컨테이너 IP를 할당할 IP 범위gateway: 마스터 서브넷의 IPv4 또는 IPv6 게이트웨이aux_addresses: 호스트명에서 IP로의 매핑으로, 네트워크 드라이버가 사용하는 보조 IPv4 또는 IPv6 주소
options: 키-값 매핑으로 드라이버별 옵션.
networks:
mynet1:
ipam:
driver: default
config:
- subnet: 172.28.0.0/16
ip_range: 172.28.5.0/24
gateway: 172.28.5.254
aux_addresses:
host1: 172.28.1.5
host2: 172.28.1.6
host3: 172.28.1.7
options:
foo: bar
baz: "0"
internal
기본적으로 Compose는 네트워크에 외부 연결성을 제공해요. internal을 true로 설정하면 외부로부터 격리된 네트워크를 만들 수 있어요.
labels
labels로 컨테이너에 메타데이터를 추가할 수 있어요. 배열 또는 딕셔너리를 사용할 수 있어요.
다른 소프트웨어와 라벨이 충돌하지 않도록 reverse-DNS 표기법을 사용하는 것이 좋아요.
networks:
mynet1:
labels:
com.example.description: "Financial transaction network"
com.example.department: "Finance"
com.example.label-with-empty-value: ""
networks:
mynet1:
labels:
- "com.example.description=Financial transaction network"
- "com.example.department=Finance"
- "com.example.label-with-empty-value"
Compose는 com.docker.compose.project와 com.docker.compose.network 라벨을 설정해요.
name
name은 네트워크의 커스텀 이름을 설정해요. name 필드는 특수 문자를 포함하는 네트워크를 참조하는 데 쓸 수 있어요. 이름은 있는 그대로 사용되고 프로젝트 이름으로 스코프가 한정되지 않아요.
networks:
network1:
name: my-app-net
external 속성과 함께 사용해 Compose가 검색해야 할 플랫폼 네트워크를 정의할 수도 있어요. 보통 Compose 파일이 런타임별 값을 하드코딩하지 않도록 매개변수를 사용해요:
networks:
network1:
external: true
name: "${NETWORK_ID}"
추가 리소스 (Additional resources)
더 많은 예시는 "Networking in Compose" 를 참고해요.
더 알아보기 (Learn more)
- Compose 네트워킹 가이드를 참고해요.