Docker 이미지를 빌드할 때 API Key, SSH Key, 인증서, 패스워드 같은 민감한 정보를 사용해야 하는 경우가 있습니다.

예:

• Private Package 설치
• Private Git Repository 접근
• API 인증
• Cloud 서비스 인증
• Database 연결 정보

하지만 이러한 정보를 Dockerfile에 직접 작성하면 보안 문제가 발생합니다.

잘못된 예:

Dockerfile

FROM node:20

ENV API_KEY="123456789"

RUN npm install

문제:

이미지 Layer

↓

환경 변수 저장

↓

Secret 노출 위험

Docker Buildx Bake에서는 Secret 기능을 사용하여 빌드 과정에서만 민감한 정보를 전달하고 Image에는 남기지 않을 수 있습니다.

예:

docker-bake.hcl

target "app" {

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

}

실행:

docker buildx bake app

결과:

Secret 전달

↓

Docker Build 실행

↓

Image 저장 안 됨

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

Docker Buildx Bake Secret이란 무엇인가?

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

일반적인 방식:

Secret

↓

Dockerfile 저장

↓

Image 포함 가능

Secret 사용:

Secret

↓

Build 과정 전달

↓

Image에는 저장되지 않음

즉, 빌드 중에만 사용할 수 있는 임시 데이터입니다.

Docker Buildx Bake Secret이 필요한 이유

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

예:

Private Repository

↓

Package Download

↓

Authentication 필요

기존 방식:

COPY secret.txt /app/

문제:

• Secret이 Image Layer에 포함
• Image 분석 시 노출 가능
• 보안 위험 증가

Secret 방식:

Secret Mount

↓

Build 사용

↓

자동 제거

장점:

• 비밀번호 보호
• API Key 보호
• 보안 강화
• 이미지 안전성 향상

Docker Buildx Bake Secret 기본 설정

docker-bake.hcl:

target "app" {

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

}

구조:

id

=

Secret 이름


src

=

Secret 파일 위치

빌드:

docker buildx bake app

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

Docker Buildx Bake Secret 환경 변수 사용 방법

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

예:

환경 변수:

export API_KEY=my-secret-key

docker-bake.hcl:

target "app" {

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

}

동작:

환경 변수

↓

Build Secret 전달

↓

Image 저장 안 됨

CI/CD 환경에서 가장 많이 사용하는 방식입니다.

Dockerfile에서 Secret 사용하기

Secret은 Dockerfile의 RUN 명령에서 사용할 수 있습니다.

예:

FROM ubuntu:22.04

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

동작:

Secret Mount

↓

RUN 실행

↓

Mount 제거

Secret 파일은 최종 Image에 남지 않습니다.

Docker Buildx Bake Secret Private Package 활용

Private Package를 설치하는 경우 유용합니다.

예:

Private NPM Package:

RUN --mount=type=secret,id=npm_token \
npm install

Bake:

target "app" {

  secret = [
    "id=npm_token,env=NPM_TOKEN"
  ]

}

활용:

• npm private package
• Python private package
• 사내 라이브러리

Docker Buildx Bake Secret SSH 사용하기

Private Git Repository 접근에는 SSH Secret을 사용할 수 있습니다.

docker-bake.hcl:

target "app" {

  ssh = [
    "default"
  ]

}

Dockerfile:

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

결과:

SSH Key

↓

Git 접근

↓

Image 저장 안 됨

Docker Buildx Bake Secret과 CI/CD 활용

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

예:

GitHub Actions:

- name: Build

  run: |

    docker buildx bake app

Secret 설정:

env:

  API_KEY: ${{ secrets.API_KEY }}

docker-bake.hcl:

target "app" {

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

}

흐름:

GitHub Secret

↓

Buildx Bake

↓

Docker Build

↓

Secret 제거

Docker Buildx Bake Secret GitLab CI 활용

GitLab CI Variables 사용:

variables:

  API_KEY: $API_KEY

Build:

script:

  - docker buildx bake app

민감한 정보가 Repository에 저장되지 않습니다.

Docker Buildx Bake Secret 실무 예제

프로젝트 구조:

project/

├── Dockerfile

├── docker-bake.hcl

└── .env

환경 변수:

DATABASE_KEY=password123

docker-bake.hcl:

target "production" {

  tags = [
    "company/app:v1"
  ]

  secret = [
    "id=db_key,env=DATABASE_KEY"
  ]

}

Dockerfile:

FROM alpine

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

실행:

docker buildx bake production

결과:

Secret 사용

↓

Build 완료

↓

Image 내부 저장 없음

Docker Buildx Bake Secret 보안 확인

Image 내부 확인:

docker history company/app:v1

확인:

Secret 정보 없음

또한:

docker inspect company/app:v1

에서도 Secret 값이 노출되지 않아야 합니다.

Docker Buildx Bake Secret 문제 해결

Secret 파일을 찾지 못하는 경우

확인:

ls secret.txt

파일 경로가 정확한지 확인합니다.

환경 변수가 전달되지 않는 경우

확인:

echo $API_KEY

환경 변수 존재 여부를 확인합니다.

Dockerfile에서 Secret 사용 오류

확인:

RUN --mount=type=secret

BuildKit 활성화가 필요합니다.

Docker Buildx Bake Secret 사용 시 주의사항

첫 번째는 Secret 값을 Dockerfile ARG나 ENV에 저장하지 않아야 합니다.

두 번째는 Git Repository에 Secret 파일을 업로드하면 안 됩니다.

세 번째는 CI/CD Secret 기능을 활용하는 것이 좋습니다.

네 번째는 최소 권한 원칙으로 Secret 접근 범위를 제한해야 합니다.

Best Practice

Docker Buildx Bake Secret 활용 방법:

• 환경 변수 Secret 사용
• CI/CD Secret 연결
• SSH 인증 활용
• Private Package 설치 활용
• Image Layer 저장 방지
• Secret 정기 교체

자주 묻는 질문

Docker Buildx Bake Secret은 무엇인가요?

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

Secret이 Docker Image에 저장되나요?

아닙니다.

Build 과정에서만 사용되고 최종 Image에는 포함되지 않습니다.

API Key를 사용할 수 있나요?

가능합니다.

환경 변수 Secret 방식으로 전달할 수 있습니다.

Private Git Repository 접근이 가능한가요?

가능합니다.

SSH Secret 기능을 활용하면 됩니다.

마무리

Docker Buildx Bake Secret은 Docker Image 빌드 과정에서 민감한 정보를 안전하게 관리하기 위한 핵심 기능입니다.

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

특히 CI/CD, Private Registry, Kubernetes 환경에서는 Secret 관리가 매우 중요하며 Docker Buildx Bake Secret을 활용하면 안전하고 자동화된 Docker 빌드 환경을 구축할 수 있습니다.