Docker 이미지를 빌드할 때 외부 공개 Repository가 아닌 Private Git Repository의 코드를 가져와야 하는 경우가 있습니다.

예:

• 사내 Git Repository
• Private GitHub Repository
• Private GitLab Repository
• SSH 인증이 필요한 소스 코드
• Private Dependency 설치

일반적인 방식으로 SSH Key를 Docker Image 내부에 복사하면 심각한 보안 문제가 발생할 수 있습니다.

잘못된 예:

Dockerfile

FROM ubuntu:22.04

COPY id_rsa /root/.ssh/id_rsa

RUN git clone git@github.com:company/private.git

문제:

SSH Key 복사

↓

Docker Layer 저장

↓

Image 분석 시 노출 위험

Docker Buildx Bake에서는 SSH Forwarding 기능을 사용하여 SSH Key를 Image에 저장하지 않고 Build 과정에서만 사용할 수 있습니다.

예:

docker-bake.hcl

target "app" {

  ssh = [
    "default"
  ]

}

Dockerfile:

FROM alpine

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의 개념부터 SSH Agent 연결, Private Repository 접근, CI/CD 활용, 보안 관리 방법까지 자세히 알아보겠습니다.

Docker Buildx Bake SSH란 무엇인가?

Docker Buildx Bake SSH는 Docker Build 과정에서 SSH 인증 정보를 안전하게 전달하는 기능입니다.

일반 방식:

SSH Key

↓

Dockerfile 복사

↓

Image 포함 가능

SSH Forwarding 방식:

SSH Agent

↓

Build 과정 전달

↓

최종 Image 저장 없음

즉, Private Repository 접근은 가능하지만 SSH Key는 Image에 남지 않습니다.

Docker Buildx Bake SSH가 필요한 이유

Private Git Repository를 사용하는 프로젝트에서는 인증이 필요합니다.

예:

Private GitHub

↓

git clone 필요

↓

SSH 인증 필요

기존 방식:

COPY ~/.ssh/id_rsa /root/.ssh/

문제:

• 개인 Key 노출 위험
• Image Layer에 기록
• 보안 취약점 발생

SSH 사용:

SSH Agent

↓

Build Container 연결

↓

Key 노출 없음

장점:

• 안전한 인증
• Private Repository 접근
• Secret 관리 단순화
• Image 보안 향상

Docker Buildx Bake SSH 기본 설정

docker-bake.hcl:

target "app" {

  context = "."

  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 Agent 연결

↓

Git 인증

↓

Repository Clone

↓

Key 제거

Docker Buildx Bake SSH 실행 방법

SSH Agent 활성화:

eval $(ssh-agent)

SSH Key 추가:

ssh-add ~/.ssh/id_rsa

확인:

ssh-add -l

Build:

docker buildx bake app

SSH 인증이 Build 과정에 전달됩니다.

Docker Buildx Bake SSH Private GitHub 사용 예제

Dockerfile:

FROM node:20

RUN apt update && apt install -y git openssh-client

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

docker-bake.hcl:

target "production" {

  tags = [
    "company/app:v1"
  ]

  ssh = [
    "default"
  ]

}

실행:

docker buildx bake production

결과:

GitHub SSH 인증

↓

Private Repository 다운로드

↓

Image 생성

Docker Buildx Bake SSH와 GitLab Private Repository 활용

GitLab Private Repository도 동일하게 사용할 수 있습니다.

Dockerfile:

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

Bake 설정:

target "app" {

  ssh = [
    "default"
  ]

}

활용:

• 사내 GitLab
• Private Package Repository
• 내부 코드 공유

Docker Buildx Bake SSH와 Private Package 설치

SSH 인증이 필요한 Package 설치에도 활용할 수 있습니다.

예:

RUN --mount=type=ssh \
    npm install git+ssh://git@github.com/company/package.git

사용:

• Private npm Package
• Private Python Package
• 내부 Library

Docker Buildx Bake SSH와 CI/CD 활용

CI 환경에서는 SSH Key를 직접 저장하지 않고 Secret 관리 기능을 사용합니다.

GitHub Actions 예:

- name: Setup SSH

  uses: webfactory/ssh-agent@v0.9.0

  with:

    ssh-private-key: ${{ secrets.SSH_KEY }}


- name: Build

  run: |

    docker buildx bake app

흐름:

GitHub Secret

↓

SSH Agent 실행

↓

Buildx Bake

↓

Private Repository 접근

Docker Buildx Bake SSH GitLab CI 활용

GitLab CI Variables 사용:

before_script:

  - eval $(ssh-agent)

  - ssh-add $SSH_PRIVATE_KEY

Build:

script:

  - docker buildx bake app

SSH Key를 Repository에 저장하지 않습니다.

Docker Buildx Bake SSH 실무 예제

프로젝트 구조:

project/

├── Dockerfile

├── docker-bake.hcl

└── .github/workflows/

docker-bake.hcl:

target "production" {

  context = "."

  tags = [
    "company/app:v1"
  ]

  ssh = [
    "default"
  ]

}

Dockerfile:

FROM ubuntu:22.04

RUN apt update && apt install -y git openssh-client

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

실행:

docker buildx bake production

결과:

SSH 인증

↓

Private Code 다운로드

↓

Docker Image 생성

Docker Buildx Bake SSH 문제 해결

Permission denied 오류

오류:

Permission denied (publickey)

확인:

ssh-add -l

SSH Key가 등록되어 있는지 확인합니다.

SSH Agent 연결 오류

확인:

echo $SSH_AUTH_SOCK

Agent 환경 변수를 확인합니다.

Git Clone 실패

확인:

• Repository 권한
• SSH Key 권한
• Git 주소

Docker Buildx Bake SSH 사용 시 주의사항

첫 번째는 SSH Key를 Dockerfile에 COPY하지 않아야 합니다.

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

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

네 번째는 사용하지 않는 SSH Key는 삭제해야 합니다.

Best Practice

Docker Buildx Bake SSH 활용 방법:

• SSH Forwarding 사용
• Dockerfile COPY 금지
• CI/CD Secret 연결
• Private Repository 접근 활용
• Deploy Key 사용
• 최소 권한 관리

자주 묻는 질문

Docker Buildx Bake SSH는 무엇인가요?

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

SSH Key가 Image에 저장되나요?

아닙니다.

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

Private GitHub Repository를 사용할 수 있나요?

가능합니다.

SSH 인증을 통해 접근할 수 있습니다.

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

가능합니다.

GitHub Actions, GitLab CI, Jenkins 등에서 활용할 수 있습니다.

마무리

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

SSH Key를 Image 내부에 저장하지 않고 Build 과정에서만 전달하기 때문에 보안성을 유지하면서 Private Code를 가져올 수 있습니다.

특히 기업 환경, CI/CD Pipeline, Private Package 관리 환경에서는 Docker Buildx Bake SSH를 활용하면 더욱 안전한 Docker 빌드 시스템을 구축할 수 있습니다.