Docker 이미지를 빌드할 때 외부 서비스와 연결하거나 Private Repository에서 파일을 가져오는 경우 비밀번호, API Key, Token 같은 민감한 정보가 필요할 수 있습니다.

예:

• Private Package Repository 인증
• AWS Access Key
• Git Token
• SSH Key
• Database 비밀번호
• Private Registry 인증 정보

가장 위험한 방법은 Dockerfile에 직접 작성하는 것입니다.

예:

ENV PASSWORD=my-password

또는:

RUN git clone https://user:password@example.com/project.git

이렇게 작성하면 이미지 Layer 기록에 정보가 남을 수 있습니다.

Docker Buildx Bake에서는 이러한 문제를 해결하기 위해 Secret 관리 기능을 제공합니다.

예:

docker-bake.hcl

target "app" {

  secret = [
    "id=mysecret,src=./secret.txt"
  ]

}

빌드 과정에서만 Secret을 사용하고 이미지에는 저장하지 않습니다.

이번 글에서는 Docker Buildx Bake Secret의 개념부터 기본 사용법, Secret 전달 방식, CI/CD 환경 활용, 안전한 Docker 이미지 빌드 방법까지 자세히 알아보겠습니다.

Docker Buildx Bake Secret이란 무엇인가?

Docker Buildx Bake Secret은 빌드 과정에서 필요한 민감한 정보를 안전하게 전달하는 기능입니다.

기본 구조:

Secret 파일

↓

Docker Build 실행

↓

빌드 과정에서만 사용

↓

이미지에는 저장하지 않음

일반 환경 변수와 달리 Secret은 Docker 이미지 Layer에 포함되지 않습니다.

Docker Buildx Bake Secret이 필요한 이유

일반적인 방식:

Dockerfile:

ARG PASSWORD

RUN echo $PASSWORD

문제:

• 이미지 기록에 남을 가능성
• 로그 노출 위험
• 보안 취약점 발생

Secret 방식:

Secret 전달

↓

Build 과정 사용

↓

빌드 종료 후 제거

장점:

• 민감 정보 보호
• 이미지 내부 저장 방지
• 안전한 자동화 가능

Docker Buildx Bake Secret 기본 사용법

docker-bake.hcl:

target "app" {

  secret = [
    "id=token,src=./token.txt"
  ]

}

Secret 파일:

token.txt

my-secret-token

빌드:

docker buildx bake app

빌드 과정에서 Token을 사용할 수 있습니다.

Dockerfile에서 Secret 사용하기

Dockerfile:

FROM ubuntu

RUN --mount=type=secret,id=token \
cat /run/secrets/token

동작:

Secret 전달

↓

/run/secrets/token 생성

↓

명령 실행

↓

Secret 제거

이미지 내부에는 Token이 남지 않습니다.

Docker Buildx Bake Secret 파일 지정 방법

파일 기반 Secret:

target "app" {

  secret = [
    "id=password,src=./password.txt"
  ]

}

구조:

project/

├── Dockerfile

├── docker-bake.hcl

└── password.txt

빌드 시:

docker buildx bake

password.txt 내용을 안전하게 전달합니다.

Docker Buildx Bake Secret 환경 변수 사용

파일 대신 환경 변수를 사용할 수도 있습니다.

예:

docker-bake.hcl

target "app" {

  secret = [
    "id=apikey,env=API_KEY"
  ]

}

환경 변수:

export API_KEY=my-api-key

빌드:

docker buildx bake

환경 변수 값을 Secret으로 전달합니다.

Docker Buildx Bake Secret과 SSH 사용

Private Git Repository를 사용하는 경우 SSH 인증이 필요할 수 있습니다.

예:

docker-bake.hcl

target "app" {

  ssh = [
    "default"
  ]

}

Dockerfile:

RUN --mount=type=ssh git clone git@github.com:company/project.git

Private Repository 접근이 가능합니다.

Docker Buildx Bake Secret 실무 활용 예제

Private Package 설치

상황:

Private npm Package 설치 필요

Dockerfile:

FROM node

RUN --mount=type=secret,id=npm \
cat /run/secrets/npm

Bake 파일:

target "app" {

  secret = [
    "id=npm,src=./npm-token"
  ]

}

효과:

• Token 보호
• 이미지 저장 방지
• 안전한 Package 설치

CI/CD에서 Docker Buildx Bake Secret 활용

GitHub Actions 환경:

- name: Build Image
  run: |
    docker buildx bake

Secret:

GitHub Secret

↓

환경 변수

↓

Docker Build Secret

활용:

• API Key 보호
• Private Registry 인증
• 배포 자동화

Docker Buildx Bake Secret과 ARG 차이

ARG 방식

Dockerfile:

ARG TOKEN

RUN echo $TOKEN

특징:

• 빌드 값 전달
• Layer 기록 가능성 존재
• 민감 정보 부적합

Secret 방식

Dockerfile:

RUN --mount=type=secret,id=token

특징:

• 빌드 중에만 사용
• 이미지 저장 안 됨
• 보안성 높음

정리:

ARG

= 일반 빌드 변수

Secret

= 민감 정보 전달

Linux 서버 문제 해결

Docker 이미지 빌드 과정에서 Private Repository 인증 정보가 필요했습니다.

기존 방식:

Dockerfile:

ARG PASSWORD

RUN git clone https://user:$PASSWORD@example.com/project.git

문제:

• Token 노출 위험
• 이미지 기록 가능성
• 보안 문제

Secret 적용:

docker-bake.hcl:

target "app" {

  secret = [
    "id=password,src=./password.txt"
  ]

}

Dockerfile:

RUN --mount=type=secret,id=password \
cat /run/secrets/password

결과:

• 인증 정보 안전 전달
• 이미지에 Secret 저장 안 됨
• 안전한 빌드 가능

Docker Buildx Bake Secret 사용 시 주의사항

첫 번째는 Secret 파일 권한을 관리해야 합니다.

두 번째는 Secret 값을 Git Repository에 저장하면 안 됩니다.

세 번째는 로그에 Secret 값이 출력되지 않도록 해야 합니다.

네 번째는 운영 환경에서는 CI Secret 관리 기능을 사용하는 것이 좋습니다.

Best Practice

Docker Buildx Bake Secret 활용 방법:

• 비밀번호는 Secret 사용
• API Key는 환경 변수 Secret 활용
• Private Repository는 SSH 사용
• Git에 Secret 파일 저장 금지
• CI/CD Secret 기능 활용
• 빌드 로그 확인

자주 묻는 질문

Docker Buildx Bake Secret은 무엇인가요?

Docker 이미지 빌드 과정에서 민감한 정보를 안전하게 전달하는 기능입니다.

Secret은 이미지에 저장되나요?

아닙니다.

빌드 과정에서만 사용되고 최종 이미지에는 포함되지 않습니다.

ARG와 Secret 차이는 무엇인가요?

ARG는 일반 빌드 변수이고, Secret은 비밀번호나 Token 같은 민감 정보 전달용입니다.

환경 변수로 Secret을 전달할 수 있나요?

가능합니다.

env 옵션을 사용하면 됩니다.

마무리

Docker Buildx Bake Secret은 안전한 Docker 이미지 빌드를 위한 중요한 기능입니다.

비밀번호, API Key, Token 같은 민감한 정보를 Dockerfile에 직접 저장하지 않고 빌드 과정에서만 사용할 수 있어 보안을 크게 향상시킬 수 있습니다.

특히 CI/CD 환경이나 Private Repository를 사용하는 프로젝트에서는 Secret 기능을 활용하면 안전하고 자동화된 Docker 빌드 환경을 구축할 수 있습니다.