Docker Image를 Build하는 과정에서는 다양한 외부 서비스와 연결해야 하는 경우가 있습니다.

예:

• Private Package Repository
• Git 인증
• API Token
• SSH Key
• Cloud 인증 정보
• Database 접근 정보

하지만 이러한 정보를 Dockerfile에 직접 입력하면 심각한 보안 문제가 발생할 수 있습니다.

잘못된 예:

RUN echo "password123" > config.txt

문제:

id="w5tq8v"
Docker Layer 저장

↓

Secret 정보 포함

↓

Image 분석 시 노출 가능

Docker Buildx Bake에서는 Secrets 기능을 사용하여 민감한 정보를 Build 과정에서만 안전하게 전달할 수 있습니다.

예:

docker-bake.hcl

target "app" {

  secret = [

    "id=npm_token,src=./token.txt"

  ]

}

실행:

docker buildx bake app

결과:

id="u8m3qd"
Secret 전달

↓

Build 과정 사용

↓

Image에는 저장되지 않음

이번 글에서는 Docker Buildx Bake Secrets의 개념부터 Secret 전달 방법, SSH 인증, Private Repository 접근, CI/CD 보안 관리까지 자세히 알아보겠습니다.

Docker Buildx Bake Secrets란 무엇인가?

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

일반적인 방식:

id="j8v4pk"
Secret 입력

↓

Dockerfile 기록

↓

Image Layer 저장

문제:

• Password 노출 가능
• Token 유출 위험
• Image 보안 문제

Secrets 방식:

id="f7n2cm"
Secret 전달

↓

Build 과정 사용

↓

Image 저장 안 함

즉, Build 중에만 Secret을 사용할 수 있습니다.

Docker Buildx Bake Secrets가 필요한 이유

Docker Build 과정에서는 인증 정보가 필요한 경우가 많습니다.

예:

id="n6z4hw"
Private Repository

↓

인증 필요

↓

Package 다운로드

일반 방식:

ARG TOKEN

RUN npm install

문제:

• Build History 노출 가능
• Image Layer 기록 가능

Secrets 사용:

id="c2m7yx"
Secret Mount

↓

명령 실행

↓

자동 제거

장점:

• 보안 강화
• Token 노출 방지
• 안전한 Build 환경

Docker Buildx Bake Secrets 기본 설정

docker-bake.hcl:

target "app" {

  secret = [

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

  ]

}

파일:

secret.txt

↓

API_TOKEN=abcdef

실행:

docker buildx bake app

Build 과정에서 Secret을 사용할 수 있습니다.

Docker Buildx Bake Secret 옵션 구조

기본 형식:

id=이름,src=파일경로

예:

secret = [

  "id=aws_key,src=./aws.txt"

]

구성:

id

↓

Secret 이름


src

↓

Secret 파일 위치

Docker Buildx Bake Secrets Dockerfile 사용 방법

Dockerfile에서는 BuildKit Secret Mount를 사용합니다.

예:

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

동작:

id="p8x4vm"
Secret 파일

↓

Container 내부 Mount

↓

명령 실행

↓

삭제

Image Layer에는 남지 않습니다.

Docker Buildx Bake Secrets 파일 전달 방식

파일 기반 Secret:

docker-bake.hcl

target "app" {

  secret = [

    "id=config,src=config.txt"

  ]

}

파일:

config.txt

내용:

USERNAME=test
PASSWORD=password

Build 과정에서만 사용됩니다.

Docker Buildx Bake Secrets 환경 변수 사용

환경 변수 기반 Secret도 가능합니다.

예:

target "app" {

  secret = [

    "id=token,env=API_TOKEN"

  ]

}

환경 변수:

export API_TOKEN=mytoken

실행:

docker buildx bake app

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

Docker Buildx Bake Secrets SSH 활용

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

예:

target "app" {

  ssh = [

    "default"

  ]

}

Dockerfile:

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

활용:

• Private Git Repository
• SSH 인증
• Secure Clone

Docker Buildx Bake Secrets Private Package 활용

예:

Private npm Repository:

id="r2y7kx"
npm Registry

↓

Token 인증

↓

Package 다운로드

docker-bake.hcl:

target "app" {

  secret = [

    "id=npmrc,src=.npmrc"

  ]

}

Dockerfile:

RUN --mount=type=secret,id=npmrc \
cp /run/secrets/npmrc ~/.npmrc && npm install

Token을 안전하게 사용할 수 있습니다.

Docker Buildx Bake Secrets CI/CD 활용

CI/CD 환경에서는 Secret 관리가 매우 중요합니다.

GitHub Actions 예:

- name: Build

  run: |

    docker buildx bake production

Bake:

target "production" {

  secret = [

    "id=token,env=TOKEN"

  ]

}

흐름:

id="m7q3za"
CI Secret 저장

↓

Build 전달

↓

Image 생성

↓

Secret 제거

Token이 Image에 포함되지 않습니다.

Docker Buildx Bake Secrets 실무 예제

프로젝트:

project/

├── Dockerfile

├── docker-bake.hcl

├── secret.txt

└── deploy.yaml

docker-bake.hcl:

target "production" {

  tags = [

    "registry.company.com/app:v1"

  ]

  secret = [

    "id=app_secret,src=secret.txt"

  ]

}

Dockerfile:

FROM alpine

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

실행:

docker buildx bake production

결과:

Secret 사용

↓

Image 생성

↓

Secret 미포함

Docker Buildx Bake Secrets 확인 방법

Image 내부 확인:

docker history image-name

Secret 정보가 없어야 합니다.

검사:

docker inspect image-name

환경 변수나 Layer에 Secret이 포함되지 않았는지 확인합니다.

Docker Buildx Bake Secrets 문제 해결

Secret 파일을 찾지 못하는 경우

오류:

failed to stat secret

확인:

ls secret.txt

파일 경로를 확인합니다.

Dockerfile에서 Secret 접근 실패

확인:

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

id 이름이 Bake 설정과 같은지 확인합니다.

CI에서 Secret 전달 실패

확인:

• CI Secret 등록
• 환경 변수 이름
• 권한 설정

Docker Buildx Bake Secrets 사용 시 주의사항

첫 번째는 Secret 파일을 Git Repository에 올리면 안 됩니다.

두 번째는 Dockerfile ARG 또는 ENV로 Secret을 전달하지 않는 것이 좋습니다.

세 번째는 CI Secret 관리 기능을 활용하는 것이 안전합니다.

네 번째는 Build 완료 후 Image 내부에 Secret이 남았는지 확인해야 합니다.

Best Practice

Docker Buildx Bake Secrets 활용 방법:

• Secret Mount 사용
• 환경 변수 Secret 활용
• SSH 인증 사용
• CI Secret 연동
• Token Image 저장 금지
• Build 후 보안 검사

자주 묻는 질문

Docker Buildx Bake Secrets는 무엇인가요?

Docker Build 과정에서 민감 정보를 안전하게 전달하는 기능입니다.

Secret이 Image에 저장되나요?

저장되지 않습니다.

Build 과정에서만 임시로 사용됩니다.

Password나 API Key를 넣어도 되나요?

가능하지만 Build 후 노출되지 않도록 Secret 방식으로 전달해야 합니다.

CI/CD에서도 사용할 수 있나요?

가능합니다.

GitHub Actions, GitLab CI 등에서 안전하게 관리할 수 있습니다.

마무리

Docker Buildx Bake Secrets는 Docker Build 과정에서 민감한 정보를 안전하게 처리하기 위한 핵심 기능입니다.

API Token, SSH Key, Private Repository 인증 정보 등을 Dockerfile이나 Image Layer에 저장하지 않고 Build 과정에서만 사용할 수 있습니다.

특히 기업 환경, CI/CD Pipeline, Private Package 관리에서는 Secrets 기능을 활용하면 보안성과 자동화 효율을 동시에 높일 수 있습니다.