Docker 이미지를 빌드하다 보면 외부 서비스 접근을 위해 민감한 정보가 필요한 경우가 있습니다.
예:
- Private 패키지 저장소 인증
- Git 저장소 접근 Token
- API Key
- SSH Key
- 인증 파일
이러한 정보를 Dockerfile에 직접 작성하면 보안 문제가 발생할 수 있습니다.
예:
ENV API_KEY=123456이런 방식은 이미지 History에 정보가 남을 수 있어 위험합니다.
Docker Buildx는 이러한 문제를 해결하기 위해 Secret Mount 기능을 제공합니다.
바로 --secret 옵션입니다.
docker buildx build --secret은 빌드 과정에서만 필요한 민감 정보를 임시로 전달하고, 최종 이미지에는 남기지 않는 기능입니다.
예:
docker buildx build \
--secret id=mysecret,src=secret.txt \
-t app:v1 .이번 글에서는 Docker Buildx Build –secret의 개념부터 기본 사용법, Secret Mount 설정, SSH 인증 활용, CI/CD 보안 관리 방법까지 자세히 알아보겠습니다.
Docker Buildx Build –secret이란 무엇인가?
--secret은 Docker 이미지 빌드 과정에서 민감한 정보를 안전하게 전달하는 옵션입니다.
기본 형식:
docker buildx build \
--secret id=이름,src=파일경로 .동작 방식:
Secret 파일
↓
Build 과정에서 임시 Mount
↓
명령 실행
↓
자동 제거최종 Docker 이미지에는 Secret 정보가 포함되지 않습니다.
Docker Buildx –secret을 사용하는 이유
일반적인 방법:
ARG PASSWORD
RUN login --password=$PASSWORD문제:
- Build History 노출 가능
- 이미지 Layer에 정보 기록 가능
- 보안 위험 발생
Secret 방식:
빌드 중 임시 사용
↓
빌드 완료 후 제거더 안전하게 관리할 수 있습니다.
Docker Buildx Build –secret 기본 사용법
Secret 파일 생성:
echo "my-password" > secret.txt빌드:
docker buildx build \
--secret id=password,src=secret.txt \
-t app:v1 .Dockerfile에서 사용합니다.
Dockerfile에서 Secret 사용하기
Secret은 BuildKit Mount 기능을 사용합니다.
Dockerfile:
# syntax=docker/dockerfile:1
FROM ubuntu
RUN --mount=type=secret,id=password \
cat /run/secrets/password빌드:
docker buildx build \
--secret id=password,src=secret.txt \
-t app:v1 .빌드 과정에서만 Secret을 사용할 수 있습니다.
Secret 파일 위치 확인하기
기본 Mount 위치:
/run/secrets/예:
/run/secrets/passwordDockerfile 안에서 해당 파일을 읽을 수 있습니다.
Docker Buildx Build –secret과 –build-arg 차이
두 기능은 비슷해 보이지만 목적이 다릅니다.
–build-arg
용도:
- 버전 정보
- 환경 설정
- 일반 빌드 변수
예:
--build-arg VERSION=1.0특징:
- 값 노출 가능성 있음
–secret
용도:
- 비밀번호
- Token
- API Key
- 인증 파일
예:
--secret id=token,src=token.txt특징:
- 빌드 후 제거
- 이미지에 포함되지 않음
정리:
일반 데이터 → --build-arg
민감 정보 → --secretDocker Buildx Build –secret SSH Key 활용
Private Git 저장소를 사용하는 경우 SSH 인증이 필요할 수 있습니다.
예:
docker buildx build \
--ssh default \
-t app:v1 .Dockerfile:
RUN --mount=type=ssh \
git clone git@github.com:company/private.gitSSH Key를 안전하게 사용할 수 있습니다.
Docker Buildx Build –secret 실무 활용 예제
Private Package 설치
Private npm 패키지가 필요합니다.
Secret 파일:
.npmrc빌드:
docker buildx build \
--secret id=npmrc,src=.npmrc \
-t frontend:v1 .Dockerfile:
RUN --mount=type=secret,id=npmrc \
npm install인증 정보가 이미지에 남지 않습니다.
CI/CD Secret 활용
GitHub Actions 예:
- name: Build Image
run: |
docker buildx build \
--secret id=token,src=token.txt \
-t app:v1 .CI 환경 변수와 함께 사용할 수 있습니다.
Linux 서버 문제 해결
Private 저장소에서 패키지를 다운로드하는 Docker 빌드가 필요했습니다.
기존 방식:
Dockerfile:
ARG TOKEN
RUN git clone https://$TOKEN@github.com/private/repo문제:
- Token이 Build History에 남음
- 보안 위험 발생
Secret 방식 적용:
RUN --mount=type=secret,id=token \
cat /run/secrets/token빌드:
docker buildx build \
--secret id=token,src=token.txt \
-t app:v1 .결과:
빌드 중 사용
↓
이미지 저장 안 됨안전하게 인증 정보를 사용할 수 있었습니다.
Docker Buildx Build –secret 사용 시 주의사항
첫 번째는 Secret 파일 권한을 관리해야 합니다.
두 번째는 Dockerfile에서 반드시 RUN --mount=type=secret을 사용해야 합니다.
세 번째는 Secret 값을 로그로 출력하지 않아야 합니다.
네 번째는 운영 환경에서는 CI Secret Manager와 함께 사용하는 것이 좋습니다.
Best Practice
Docker Buildx Build –secret 활용 방법:
- 비밀번호는 Secret 사용
- API Key는 Secret 사용
- Token은 Secret 사용
- Build Arg와 목적 구분
- Secret 파일 권한 관리
- CI/CD Secret 기능 활용
자주 묻는 질문
Docker Buildx Build –secret은 무엇인가요?
Docker 빌드 과정에서 민감 정보를 안전하게 전달하는 기능입니다.
Secret 정보가 이미지에 저장되나요?
아닙니다.
빌드 과정에서만 임시 사용됩니다.
–build-arg 대신 –secret을 사용해야 하나요?
민감 정보라면 반드시 Secret 사용을 권장합니다.
SSH Key도 사용할 수 있나요?
가능합니다.
--ssh 옵션을 활용할 수 있습니다.
마무리
Docker Buildx Build –secret은 안전한 Docker 이미지 빌드를 위한 필수 기능입니다.
비밀번호, API Key, Token 같은 민감 정보를 Dockerfile이나 이미지 Layer에 남기지 않고 빌드 과정에서만 사용할 수 있습니다.
특히 CI/CD 환경과 Private Repository를 사용하는 프로젝트에서는 --secret을 활용하면 보안성과 자동화 수준을 동시에 높일 수 있습니다.