Docker Image를 Build하는 과정에서는 외부 Repository에서 코드를 가져와야 하는 경우가 많습니다.

특히 실제 서버 환경에서는 다음과 같은 상황이 자주 발생합니다.

• Private Git Repository 사용
• 회사 내부 코드 저장소 접근
• SSH 인증 필요
• 배포 자동화 환경 구축

일반적인 방식:

RUN git clone https://token@github.com/private/project.git

문제:

Token 저장

↓

Docker Layer 기록

↓

보안 위험 발생

또는 SSH Key를 직접 복사하는 방식:

COPY id_rsa /root/.ssh/

문제:

Private Key 포함

↓

Image 유출 시 위험

Docker Buildx Bake에서는 SSH Mount 기능을 사용하여 Build 과정에서만 SSH 인증 정보를 안전하게 전달할 수 있습니다.

예:

docker-bake.hcl

target "app" {

  ssh = [

    "default"

  ]

}

Dockerfile:

FROM alpine

RUN apk add git openssh

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

실행:

docker buildx bake app

결과:

SSH Key 전달

↓

Private Repository 접근

↓

Build 완료

↓

SSH Key 제거

Docker Buildx Bake SSH란 무엇인가?

Docker Buildx Bake SSH는 Build 과정에서 SSH 인증을 임시로 연결하는 기능입니다.

구조:

SSH Key

↓

Build Container

↓

Git Repository 접근

↓

Build 종료 후 제거

중요한 특징:

• SSH Key가 Image에 저장되지 않음
• Docker Layer에 기록되지 않음
• Private Repository 접근 가능

Docker Buildx Bake SSH가 필요한 이유

Private Repository 환경에서는 인증이 필요합니다.

예:

GitHub Private Repository

↓

인증 필요

↓

Source 다운로드

잘못된 방법:

ENV SSH_KEY=value

문제:

• Image History 노출 가능
• 보안 위험

올바른 방법:

RUN --mount=type=ssh

장점:

• 안전한 인증
• 자동화 가능
• CI/CD 적합

Docker Buildx Bake SSH 기본 설정

docker-bake.hcl

target "production" {

  ssh = [

    "default"

  ]

}

의미:

default SSH Agent 사용

↓

Build 과정 연결

실행:

docker buildx bake production

Docker Buildx Bake SSH Dockerfile 설정

Dockerfile:

FROM ubuntu

RUN apt update && apt install git -y

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

동작:

SSH Agent 연결

↓

Git 인증

↓

Repository Clone

Docker Buildx Bake SSH GitHub Private Repository 연결

예:

github.com/company/private-project

SSH 주소:

git@github.com:company/private-project.git

Dockerfile:

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

Build:

docker buildx bake app

결과:

Private Repository

↓

안전하게 Clone

↓

Image Build

Docker Buildx Bake SSH CI/CD 활용

실제 서버 운영에서는 CI/CD에서 SSH 인증을 많이 사용합니다.

예:

GitHub Actions:

- name: Build

  uses: docker/build-push-action@v6

  with:

    ssh: default

흐름:

Git Push

↓

GitHub Actions 실행

↓

SSH Agent 연결

↓

Docker Build

↓

Image 생성

Docker Buildx Bake SSH와 Secret 차이

둘 다 인증 정보를 전달하지만 목적이 다릅니다.

Secret:

Token
API Key
Password

사용:

RUN --mount=type=secret

SSH:

SSH Key
Git 인증

사용:

RUN --mount=type=ssh

비교:

기능	용도
Secret	일반 민감 정보
SSH	Git SSH 인증

Docker Buildx Bake SSH 실무 프로젝트 예제

구조:

project/

├── Dockerfile

├── docker-bake.hcl

└── src/

docker-bake.hcl:

target "production" {

  tags = [

    "registry.company.com/app:v1"

  ]

  ssh = [

    "default"

  ]

}

Dockerfile:

FROM node:20

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

RUN npm install

실행:

docker buildx bake production

결과:

SSH 인증

↓

Private Code 다운로드

↓

Application Build

Docker Buildx Bake SSH 문제 해결

Permission denied 오류

확인:

ssh -T git@github.com

SSH 인증 상태 확인

SSH Agent 연결 오류

확인:

echo $SSH_AUTH_SOCK

CI/CD에서 실패하는 경우

확인:

• SSH Key 등록
• Agent 실행
• Repository 권한

Docker Buildx Bake SSH 사용 시 주의사항

첫 번째는 SSH Private Key를 Image 안에 복사하지 않습니다.

두 번째는 CI/CD Secret 관리 기능과 함께 사용하는 것이 좋습니다.

세 번째는 최소 권한 SSH Key를 사용하는 것이 안전합니다.

네 번째는 Production 환경에서는 Deploy 전용 Key를 사용하는 것이 좋습니다.

Best Practice

Docker Buildx Bake SSH 활용 방법:

• Private Repository 접근
• SSH Agent 활용
• CI/CD 연동
• Key 직접 복사 금지
• 최소 권한 적용
• Build 후 인증 정보 제거

자주 묻는 질문

Docker Buildx Bake SSH는 무엇인가요?

Build 과정에서 SSH 인증을 안전하게 전달하는 기능입니다.

SSH Key가 Image에 포함되나요?

아닙니다.

Build 과정에서만 사용되고 제거됩니다.

Private Git Repository도 사용할 수 있나요?

가능합니다.

GitHub, GitLab 등 SSH 인증 Repository에 사용할 수 있습니다.

Secret과 SSH 차이는 무엇인가요?

Secret은 일반 민감 정보, SSH는 Git 인증에 특화되어 있습니다.

마무리

Docker Buildx Bake SSH는 Private Repository와 안전하게 연결하기 위한 중요한 기능입니다.

SSH Key를 직접 Image에 포함하면 보안 문제가 발생할 수 있지만, Buildx SSH Mount를 사용하면 Build 과정에서만 인증 정보를 사용하고 안전하게 제거할 수 있습니다.

특히 기업 서버 환경, CI/CD Pipeline, Private Source Code 관리에서는 Docker Buildx Bake SSH 활용이 필수적인 기술입니다.