Docker Image를 Build하는 과정에서는 다양한 민감한 정보가 필요할 수 있습니다.

예:

• Private Repository Token
• API Key
• SSH Key
• Package 인증 정보
• Cloud Access Key

일반적인 방식으로 정보를 전달하면 문제가 발생할 수 있습니다.

예:

ARG TOKEN

RUN git clone https://$TOKEN@github.com/private/repository

문제:

Build Layer 저장

↓

Token 정보 노출 가능

↓

보안 위험 발생

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

예:

docker-bake.hcl

target "production" {

  secret = [

    "id=mytoken,src=token.txt"

  ]

}

실행:

docker buildx bake production

결과:

Secret 전달

↓

Build 과정 사용

↓

Image Layer 저장 안 됨

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

Docker Buildx Bake Secrets란 무엇인가?

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

기본 구조:

Secret 저장

↓

Build 실행

↓

임시 전달

↓

Build 종료 후 제거

중요한 특징:

• Image Layer에 저장되지 않음
• Docker History에 노출되지 않음
• Build 과정에서만 사용

Docker Buildx Bake Secrets가 필요한 이유

일반적인 환경 변수 전달:

ENV PASSWORD=my-password

문제:

Image 생성

↓

환경 변수 저장

↓

정보 노출 가능

Secret 사용:

Secret 전달

↓

RUN 명령 실행

↓

자동 제거

장점:

• 인증 정보 보호
• Token 노출 방지
• 보안 Build 가능

Docker Buildx Bake Secret 기본 사용법

Secret 파일 생성:

echo "my-secret-token" > token.txt

Bake 설정:

target "app" {

  secret = [

    "id=token,src=token.txt"

  ]

}

실행:

docker buildx bake app

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

Docker Buildx Bake Secret Dockerfile 사용법

Dockerfile:

FROM alpine

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

동작:

Secret Mount

↓

파일 접근

↓

명령 실행

↓

Secret 제거

Secret 파일은 Image에 포함되지 않습니다.

Docker Buildx Bake Secret 환경 변수 사용

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

예:

export API_KEY="abcdef12345"

Bake:

target "app" {

  secret = [

    "id=apikey,env=API_KEY"

  ]

}

실행:

docker buildx bake app

환경 변수 Secret을 Build에 전달합니다.

Docker Buildx Bake Secret Private Repository 활용

Private Repository에서 코드를 가져오는 경우 Secret이 필요합니다.

예:

Private Git Repository

↓

Access Token 필요

↓

Source Download

설정:

target "app" {

  secret = [

    "id=git_token,src=token.txt"

  ]

}

Dockerfile:

RUN --mount=type=secret,id=git_token \
    git clone private-repository

인증 정보를 안전하게 사용할 수 있습니다.

Docker Buildx Bake Secret SSH Key 활용

SSH 인증도 Secret 방식으로 처리할 수 있습니다.

예:

target "app" {

  ssh = [

    "default"

  ]

}

Dockerfile:

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

활용:

• Private Git
• SSH 인증
• 내부 Repository

Docker Buildx Bake Secret CI/CD 활용

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

예:

GitHub Actions:

- name: Build Image

  run: |

    docker buildx bake production

Secret 설정:

env:

  TOKEN: ${{ secrets.TOKEN }}

Bake:

target "production" {

  secret = [

    "id=token,env=TOKEN"

  ]

}

흐름:

GitHub Secret

↓

Buildx Bake

↓

Docker Build

↓

Secret 제거

Docker Buildx Bake Secret과 Image 보안

일반 ARG 사용:

ARG PASSWORD

문제:

History 기록 가능

Secret 사용:

RUN --mount=type=secret

결과:

Build 과정만 사용

↓

Image 저장 없음

Production 환경에서 권장되는 방식입니다.

Docker Buildx Bake Secret 실무 예제

프로젝트:

project/

├── Dockerfile

├── docker-bake.hcl

└── secrets/

    └── token.txt

docker-bake.hcl:

target "production" {

  tags = [

    "registry.company.com/app:v1"

  ]

  secret = [

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

  ]

  output = [

    "type=image,push=true"

  ]

}

Dockerfile:

FROM alpine

RUN --mount=type=secret,id=token \
    echo "Using Secret"

실행:

docker buildx bake production

결과:

Secret 사용

↓

Image 생성

↓

Secret 미포함

Docker Buildx Bake Secret 확인 방법

Build 설정 확인:

docker buildx bake production --print

Secret 설정 확인:

secret

↓

id 확인

↓

src 확인

Image 확인:

docker history image-name

Secret 정보가 저장되지 않았는지 확인합니다.

Docker Buildx Bake Secret 문제 해결

Secret 파일을 찾지 못하는 경우

확인:

ls secrets/

파일 경로를 확인합니다.

Secret Mount 오류

확인:

Dockerfile:

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

Bake:

secret = [
"id=name,src=file"
]

ID가 동일해야 합니다.

CI/CD Secret 전달 실패

확인:

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

Docker Buildx Bake Secret 사용 시 주의사항

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

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

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

네 번째는 최소한의 권한만 가진 Token을 사용하는 것이 좋습니다.

Best Practice

Docker Buildx Bake Secrets 활용 방법:

• Token 보호
• API Key 보호
• SSH 인증 관리
• CI/CD Secret 활용
• Private Repository 접근
• Image Layer 보안 유지

자주 묻는 질문

Docker Buildx Bake Secrets는 무엇인가요?

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

Secret이 Image에 저장되나요?

아닙니다.

Build 과정에서만 사용되고 Image Layer에는 저장되지 않습니다.

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

ARG는 Build 정보로 남을 가능성이 있지만 Secret은 임시 전달 방식입니다.

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

가능합니다.

GitHub Actions Secret 등과 함께 사용할 수 있습니다.

마무리

Docker Buildx Bake Secrets는 안전한 Docker Image Build 환경을 만들기 위한 필수 기능입니다.

API Key, Token, SSH Key 같은 민감한 정보를 일반적인 환경 변수나 ARG로 전달하면 보안 위험이 발생할 수 있습니다.

Secret 기능을 활용하면 필요한 순간에만 정보를 전달하고 Build 결과에는 남기지 않아 더욱 안전한 Container 환경을 구축할 수 있습니다.

특히 Production 환경과 CI/CD Pipeline에서는 Docker Buildx Bake Secrets를 활용하는 것이 안전한 Image 관리의 핵심입니다.