Dockerfile에 프록시 설정을 추가하지 않고 빌드에만 적용하려면 docker build --build-arg HTTP_PROXY=http://proxy.example.com:3128 .처럼 프록시 빌드 인자를 전달하면 됩니다. 프록시 인자는 미리 정의되어 있으므로 Dockerfile에 ARG HTTP_PROXY를 선언하거나 값을 직접 참조할 필요가 없습니다.
빌드 환경마다 프록시 주소가 다를 때 사용하는 방법
회사 네트워크에서 의존성을 내려받는 빌드에만 프록시가 필요하다면, 주소를 Dockerfile에 고정하는 대신 빌드 명령에서 전달할 수 있습니다. 같은 Dockerfile을 유지하면서 빌드를 호출하는 환경에 맞춰 프록시 값을 지정하는 방식입니다.
ENV HTTP_PROXY=...를 추가하면 해당 환경변수가 이미지에서 실행하는 컨테이너에도 유지됩니다. 빌드에만 필요한 설정이라면 프록시 빌드 인자로 전달하고, 이를 다시 ENV나 설정 파일에 저장하지 않는 구성이 목적에 맞습니다.
프록시 빌드 인자 전달하기
Docker가 지원하는 프록시 빌드 인자는 HTTP_PROXY, HTTPS_PROXY, FTP_PROXY, NO_PROXY, ALL_PROXY입니다. 이 인자들의 이름은 대소문자를 구분하지 않습니다. 필요한 인자마다 --build-arg를 붙여 전달합니다.
docker build \
--build-arg HTTP_PROXY=http://proxy.example.com:3128 \
--build-arg HTTPS_PROXY=http://proxy.example.com:3128 \
-t app:proxy-build .주소와 포트는 실제 사용할 프록시로 바꿔야 합니다. 마지막의 .은 현재 디렉터리를 빌드 컨텍스트로 지정합니다. 이 명령은 해당 빌드에 프록시 설정을 제공하며, 실행할 컨테이너의 기본 프록시 환경변수를 설정하는 명령은 아닙니다.
예제: 의존성 설치 단계에 프록시 제공하기
다음은 Node.js 프로젝트의 예시 Dockerfile입니다. 프록시 관련 ARG나 ENV를 넣지 않은 상태로 사용합니다.
FROM node:20
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .예제의 전제는 Docker 빌드를 실행할 수 있고, 프로젝트에 npm ci에 필요한 package.json과 일치하는 잠금 파일이 있다는 것입니다. 빌드 환경에서 프록시 주소에 접근할 수 있어야 하며, 의존성 설치 도구가 전달된 프록시 설정을 사용할 수 있어야 합니다. 베이스 이미지와 프로젝트의 Node.js 요구사항도 별도로 맞춰야 합니다.
이 Dockerfile이 있는 디렉터리에서 앞의 빌드 명령을 사용합니다. 기대되는 동작은 RUN npm ci 같은 빌드 중 네트워크 작업에 프록시 설정이 제공되는 것입니다. 프록시 인자가 전달되었다는 사실만으로 의존성 설치 성공까지 보장되지는 않습니다. 접근 권한이나 네트워크 연결 등의 조건은 충족되어야 합니다.
Dockerfile에서 직접 참조하면 캐시 기록 조건이 달라집니다
프록시 빌드 인자에는 일반 빌드 인자와 다른 기본 처리가 있습니다. Dockerfile에서 선언하거나 참조하지 않고 전달하면, 기본적으로 프록시 인자는 빌드 캐시와 docker history 출력에서 제외됩니다.
| 사용 방식 | 기록에 대한 해석 |
|---|---|
| 명령의 --build-arg로만 전달 | 기본적으로 프록시 인자가 빌드 캐시와 docker history 출력에서 제외됩니다. |
| Dockerfile에서 프록시 인자를 직접 참조 | 프록시 설정이 빌드 캐시에 포함되므로 기본 제외 처리를 기대하면 안 됩니다. |
| ENV 또는 파일에 값을 저장 | 이미지의 실행 환경이나 파일에 설정을 남길 수 있습니다. |
예를 들어 전달 여부를 확인하려고 다음 코드를 추가하면, 프록시 인자를 직접 참조하는 구성이 됩니다.
ARG HTTP_PROXY
RUN echo "$HTTP_PROXY"이 코드는 권장 예제가 아닙니다. 프록시 설정을 캐시에 포함시키는 데 더해, 값을 빌드 로그에도 출력합니다. 빌드에 프록시를 제공하는 목적이라면 이런 확인용 참조는 필요하지 않습니다.
기본 제외 처리를 비밀값 보호로 오해하지 않기
빌드 캐시와 history에서 기본 제외된다는 설명은 모든 로그나 저장 경로에서 비밀값을 보호한다는 뜻이 아닙니다. 인증정보를 포함한 프록시 값을 출력하거나 파일에 기록하지 않아야 합니다. 일반적으로 ARG와 ENV는 비밀값 전달 수단으로 적절하지 않으며, 빌드에 비밀값이 필요하면 secret mount 같은 별도 수단을 검토해야 합니다.
실무에서는 빌드 명령에 필요한 프록시 인자만 추가하고, Dockerfile에 프록시 선언·참조·저장이 들어갔는지 확인하세요. 이 경계를 지키면 빌드용 네트워크 설정과 이미지에 남길 설정을 구분할 수 있습니다.