Docker 이미지를 빌드하는 과정에서는 외부 패키지를 다운로드하거나 내부 서버에 접근해야 하는 경우가 있습니다.
예:
- Ubuntu 패키지 설치
- npm 패키지 다운로드
- Private Repository 접근
- 사내 패키지 서버 연결
- 네트워크 테스트
하지만 Docker Buildx Build는 기본적으로 격리된 네트워크 환경에서 빌드가 실행됩니다.
이 때문에 다음과 같은 문제가 발생할 수 있습니다.
패키지 다운로드 실패
내부 서버 접근 불가
DNS 오류 발생
네트워크 연결 실패이때 사용하는 옵션이 바로 Docker Buildx Build –network입니다.
--network 옵션은 Docker 이미지 빌드 과정에서 사용할 네트워크 방식을 지정하는 기능입니다.
예:
docker buildx build \
--network host \
-t app:v1 .빌드 과정에서 사용할 네트워크 환경을 변경할 수 있습니다.
이번 글에서는 Docker Buildx Build –network의 개념부터 네트워크 모드 종류, Host Network 사용법, 실무 활용 방법까지 자세히 알아보겠습니다.
Docker Buildx Build –network란 무엇인가?
--network는 Docker 빌드 과정에서 RUN 명령어가 사용할 네트워크 환경을 지정하는 옵션입니다.
기본 형식:
docker buildx build \
--network 네트워크모드 .예:
docker buildx build \
--network host \
-t app:v1 .빌드 단계의 네트워크 동작을 변경합니다.
Docker Buildx 기본 네트워크 동작
기본 빌드 환경:
Build Container
↓
격리된 Network
↓
외부 접근Docker는 보안을 위해 빌드 환경을 분리합니다.
하지만 일부 프로젝트에서는 추가 네트워크 접근이 필요합니다.
Docker Buildx Build –network 사용 이유
다음 상황에서 사용합니다.
- 패키지 다운로드 문제 해결
- 내부 서버 접근
- 사내 Registry 연결
- DNS 문제 해결
- 네트워크 환경 테스트
특히 기업 내부 환경에서는 자주 사용됩니다.
Docker Buildx Build –network 기본 사용법
Host Network 사용:
docker buildx build \
--network host \
-t app:v1 .빌드 컨테이너가 호스트 네트워크를 사용할 수 있습니다.
Docker Buildx Build –network 주요 모드
대표적인 네트워크 모드:
| 모드 | 설명 |
|---|---|
| default | 기본 Docker 네트워크 |
| host | 호스트 네트워크 사용 |
| none | 네트워크 차단 |
–network default 사용법
기본 설정입니다.
예:
docker buildx build \
--network default \
-t app:v1 .일반적인 빌드 환경입니다.
–network host 사용법
호스트 네트워크를 사용합니다.
예:
docker buildx build \
--network host \
-t app:v1 .활용:
- 내부 API 접근
- 사내 서버 연결
- 특정 DNS 환경 사용
–network none 사용법
네트워크를 완전히 차단합니다.
예:
docker buildx build \
--network none \
-t app:v1 .보안이 중요한 빌드 환경에서 사용할 수 있습니다.
Dockerfile RUN 명령과 –network 관계
Dockerfile:
FROM ubuntu
RUN apt update기본:
docker buildx build .네트워크 문제 발생 가능:
Unable to connect repositoryHost Network:
docker buildx build \
--network host .패키지 다운로드가 정상적으로 진행됩니다.
Docker Buildx Build –network 실무 활용 예제
Private Package Server 접근
상황:
사내 패키지 서버:
192.168.0.100접근 필요:
docker buildx build \
--network host \
-t internal-app:v1 .내부 네트워크 접근이 가능합니다.
CI/CD 환경 활용
CI 서버에서:
docker buildx build \
--network host \
-t company/app:${VERSION} \
--push .내부 서비스 접근이 필요한 빌드 환경에서 활용할 수 있습니다.
Linux 서버 문제 해결
Docker 이미지 빌드 중 패키지 설치 오류가 발생했습니다.
Dockerfile:
FROM ubuntu
RUN apt update빌드:
docker buildx build \
-t app:v1 .오류:
Could not resolve archive.ubuntu.com네트워크 문제였습니다.
해결:
docker buildx build \
--network host \
-t app:v1 .다시 빌드:
docker buildx build \
-t app:v1 .정상적으로 패키지를 다운로드할 수 있었습니다.
Docker Buildx Build –network 사용 시 주의사항
첫 번째는 host 모드는 격리 수준이 낮아질 수 있습니다.
두 번째는 운영 환경에서는 필요한 경우에만 사용해야 합니다.
세 번째는 네트워크 접근 권한을 신중하게 관리해야 합니다.
네 번째는 단순한 패키지 오류라면 먼저 DNS와 Proxy 설정을 확인해야 합니다.
Best Practice
Docker Buildx Build –network 활용 방법:
- 기본 network부터 사용
- 필요한 경우만 host 사용
- Private 환경에서 제한적으로 적용
- CI/CD 권한 관리
- 네트워크 문제 분석 후 적용
- 보안 환경에서는 최소 권한 유지
자주 묻는 질문
Docker Buildx Build –network는 무엇인가요?
Docker 빌드 과정에서 사용할 네트워크 방식을 지정하는 옵션입니다.
host 네트워크는 언제 사용하나요?
빌드 과정에서 호스트 네트워크 접근이 필요할 때 사용합니다.
기본 네트워크가 가장 안전한가요?
네.
일반적인 Docker 빌드에서는 기본 설정 사용을 권장합니다.
네트워크를 차단할 수도 있나요?
가능합니다.
--network none을 사용할 수 있습니다.
마무리
Docker Buildx Build –network는 Docker 이미지 빌드 과정의 네트워크 환경을 제어하는 중요한 옵션입니다.
기본 네트워크 환경으로 충분한 경우도 많지만, 내부 서버 접근이나 특정 패키지 다운로드가 필요한 환경에서는 --network host를 활용하여 문제를 해결할 수 있습니다.
다만 Host Network는 보안 격리 수준을 낮출 수 있기 때문에 필요한 상황에서만 제한적으로 사용하는 것이 안정적인 Docker 운영 방법입니다.