Docker Image를 Build하는 과정에서는 외부 Git Repository에서 코드를 가져오거나 Private Repository에 접근해야 하는 경우가 있습니다.

예:

• Private GitHub Repository Clone
• GitLab Private Repository 접근
• SSH 인증 필요
• 내부 소스 코드 다운로드
• Private Package 설치

하지만 SSH Key를 Dockerfile 안에 직접 복사하면 심각한 보안 문제가 발생할 수 있습니다.

잘못된 예:

COPY id_rsa /root/.ssh/id_rsa

문제:

SSH Key 포함

↓

Docker Layer 저장

↓

Image 분석 시 노출 가능

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

예:

docker-bake.hcl

target "app" {

  ssh = [

    "default"

  ]

}

실행:

docker buildx bake app

Dockerfile:

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

결과:

SSH Key 전달

↓

Private Repository 접근

↓

Build 완료

↓

SSH 정보 미저장

이번 글에서는 Docker Buildx Bake SSH의 개념부터 SSH 설정 방법, Private Repository 연결, CI/CD 활용, 보안 관리까지 자세히 알아보겠습니다.

Docker Buildx Bake SSH란 무엇인가?

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

일반 방식:

SSH Key

↓

Dockerfile 복사

↓

Image 저장

문제:

• Key 노출 위험
• 보안 취약점 발생
• 관리 어려움

SSH Mount 방식:

SSH Agent

↓

Build Container 연결

↓

명령 실행

↓

자동 제거

즉, SSH 인증 정보를 Image에 포함하지 않고 Build 과정에서만 사용할 수 있습니다.

Docker Buildx Bake SSH가 필요한 이유

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

예:

Private Git Repository

↓

인증 필요

↓

Source Code Clone

일반적인 방법:

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

문제:

• Private Key 노출
• Image Layer 기록
• 보안 사고 위험

SSH 방식:

SSH Agent

↓

임시 연결

↓

Git Clone

↓

Key 제거

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

Docker Buildx Bake SSH 기본 설정

docker-bake.hcl:

target "app" {

  ssh = [

    "default"

  ]

}

실행:

docker buildx bake app

SSH Agent를 Build 과정에서 사용할 수 있습니다.

Docker Buildx Bake SSH Dockerfile 설정

Dockerfile:

FROM alpine

RUN apk add git openssh


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

동작:

SSH 연결

↓

Git 인증

↓

Repository Clone

↓

SSH 정보 제거

Image에는 Key가 남지 않습니다.

Docker Buildx Bake SSH 옵션 종류

default SSH 사용

가장 일반적인 방식입니다.

ssh = [
  "default"
]

현재 SSH Agent를 사용합니다.

특정 SSH Key 지정

예:

ssh = [

  "mykey=/home/user/.ssh/id_rsa"

]

특정 Key를 지정할 수 있습니다.

구조:

id=SSH 이름

↓

Key 파일 위치

Docker Buildx Bake SSH GitHub Repository 연결

예:

Private Repository:

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

docker-bake.hcl:

target "app" {

  ssh = [

    "default"

  ]

}

Dockerfile:

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

실행:

docker buildx bake app

결과:

GitHub 인증

↓

Repository Clone

↓

Image Build

Docker Buildx Bake SSH GitLab 활용

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

예:

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

활용:

• Private Source Code
• 내부 Library
• 사내 Repository

Docker Buildx Bake SSH와 Known Hosts 설정

SSH 연결 시 Host 인증이 필요합니다.

Dockerfile:

RUN mkdir -p ~/.ssh

RUN ssh-keyscan github.com >> ~/.ssh/known_hosts

동작:

GitHub Host 확인

↓

SSH 연결

↓

Clone 실행

보안을 위해 Host 검증을 권장합니다.

Docker Buildx Bake SSH CI/CD 활용

CI/CD 환경에서는 SSH Key를 안전하게 관리해야 합니다.

GitHub Actions 예:

- name: Build

  run: |

    docker buildx bake production

Bake:

target "production" {

  ssh = [

    "default"

  ]

}

흐름:

CI Secret 관리

↓

SSH Agent 실행

↓

Build 연결

↓

Image 생성

SSH Key가 Image에 포함되지 않습니다.

Docker Buildx Bake SSH 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

↓

Docker Build

↓

Private Repository 접근

Docker Buildx Bake SSH 실무 예제

프로젝트:

project/

├── Dockerfile

├── docker-bake.hcl

└── private-source/

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-library.git

실행:

docker buildx bake production

결과:

SSH 인증

↓

Private Library 다운로드

↓

Image 생성

Docker Buildx Bake SSH 문제 해결

Permission denied 오류

오류:

Permission denied (publickey)

확인:

ssh -T git@github.com

SSH 인증 상태를 확인합니다.

SSH Agent 연결 실패

확인:

ssh-add -l

등록된 Key를 확인합니다.

Dockerfile에서 SSH 사용 불가

확인:

RUN --mount=type=ssh

BuildKit 사용 여부를 확인합니다.

Docker Buildx Bake SSH 사용 시 주의사항

첫 번째는 SSH Key를 Dockerfile에 직접 복사하면 안 됩니다.

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

세 번째는 Host 검증을 설정하는 것이 좋습니다.

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

Best Practice

Docker Buildx Bake SSH 활용 방법:

• SSH Mount 사용
• Private Key Image 저장 금지
• SSH Agent 활용
• CI Secret 연결
• Known Hosts 설정
• Private Repository 안전 관리

자주 묻는 질문

Docker Buildx Bake SSH는 무엇인가요?

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

SSH Key가 Image에 저장되나요?

저장되지 않습니다.

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

Private Git Repository를 Clone할 수 있나요?

가능합니다.

GitHub, GitLab 등 Private Repository 접근에 사용할 수 있습니다.

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

가능합니다.

SSH Secret과 Agent를 연결하여 사용할 수 있습니다.

마무리

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

SSH Key를 Image 내부에 저장하지 않고 Build 과정에서만 사용할 수 있기 때문에 보안성과 관리 편의성을 동시에 높일 수 있습니다.

특히 기업 프로젝트, Private Git Repository, CI/CD 자동화 환경에서는 SSH 기능을 활용하면 안전한 Docker Build 환경을 구축할 수 있습니다.