Docker 이미지를 빌드하다 보면 Private Git Repository에서 소스 코드를 가져오거나 SSH 인증이 필요한 패키지를 설치해야 하는 경우가 있습니다.

예:

• Private GitHub Repository Clone
• Private GitLab Repository 접근
• SSH Key 기반 인증
• 내부 서버 코드 다운로드
• Private Package 설치

일반적인 방식으로 SSH Key를 Docker 이미지 빌드 과정에 넣으면 보안 문제가 발생할 수 있습니다.

예:

COPY id_rsa /root/.ssh/

문제:

• SSH Key가 이미지 Layer에 남음
• Key 유출 위험
• 보안 취약점 발생

Docker Buildx Bake에서는 이러한 문제를 해결하기 위해 SSH Forwarding 기능을 제공합니다.

예:

docker-bake.hcl

target "app" {

  ssh = [
    "default"
  ]

}

Dockerfile:

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

빌드 과정에서만 SSH 인증을 사용하고 이미지에는 Key가 저장되지 않습니다.

이번 글에서는 Docker Buildx Bake SSH의 개념부터 기본 사용법, Private Repository 접근, CI/CD 활용 방법까지 자세히 알아보겠습니다.

Docker Buildx Bake SSH란 무엇인가?

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

기본 구조:

SSH Agent

↓

Docker Build

↓

Private Repository 접근

↓

SSH Key 미저장

SSH Key 자체를 이미지 내부로 복사하지 않고 빌드 과정에서만 사용할 수 있습니다.

Docker Buildx Bake SSH가 필요한 이유

잘못된 방법:

Dockerfile:

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

문제:

• Private Key 노출 위험
• 이미지 Layer에 기록
• 보안 관리 어려움

SSH Mount 방식:

RUN --mount=type=ssh git clone repository

장점:

• Key가 이미지에 저장되지 않음
• 안전한 인증 가능
• CI/CD 환경 활용 가능

Docker Buildx Bake SSH 기본 사용법

docker-bake.hcl:

target "app" {

  ssh = [
    "default"
  ]

}

Dockerfile:

FROM ubuntu

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

빌드:

docker buildx bake app

SSH Agent를 통해 인증합니다.

Docker Buildx Bake SSH 활성화 조건

SSH 기능을 사용하려면 다음 조건이 필요합니다.

필요 조건:

• BuildKit 활성화
• SSH Agent 실행
• Dockerfile에서 SSH Mount 사용
• Bake 파일 SSH 설정

확인:

ssh-add -l

등록된 SSH Key를 확인할 수 있습니다.

Docker Buildx Bake SSH와 SSH Key 연결하기

SSH Key 등록:

ssh-add ~/.ssh/id_rsa

Bake 파일:

target "app" {

  ssh = [
    "default"
  ]

}

빌드:

docker buildx bake

등록된 SSH Key를 사용합니다.

Docker Buildx Bake SSH와 Private Git Repository 사용

Dockerfile:

FROM alpine


RUN apk add git


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

Bake 파일:

target "app" {

  ssh = [
    "default"
  ]

}

실행:

docker buildx bake

Private Repository에서 코드를 가져올 수 있습니다.

Docker Buildx Bake SSH와 GitHub 활용

GitHub Private Repository:

git@github.com:organization/project.git

Dockerfile:

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

SSH 인증 후 소스를 가져옵니다.

최종 이미지에는:

• SSH Key 없음
• 인증 정보 없음

안전한 빌드가 가능합니다.

Docker Buildx Bake SSH 실무 활용 예제

Private Package 설치

상황:

내부 Git Repository에서 Package 설치 필요

Dockerfile:

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

Bake 파일:

target "backend" {

  ssh = [
    "default"
  ]

}

효과:

• Private Package 접근
• SSH Key 보호
• 이미지 보안 유지

CI/CD에서 Docker Buildx Bake SSH 활용

CI 환경에서는 SSH Key를 Secret으로 관리합니다.

예:

GitHub Actions:

- name: Build Image
  run: |
    docker buildx bake

구성:

CI Secret

↓

SSH Agent

↓

Docker Build

↓

Private Repository 접근

활용:

• Private Git Clone
• 내부 Package 설치
• 자동 배포

Docker Buildx Bake SSH와 Secret 차이

SSH

용도:

• Git 인증
• SSH 서버 접근
• Private Repository

예:

ssh = [
  "default"
]

Secret

용도:

• API Key
• Password
• Token

예:

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

정리:

SSH

= SSH 인증 정보 전달

Secret

= 일반 민감 정보 전달

Linux 서버 문제 해결

Docker 이미지 빌드 중 Private Repository Clone 오류가 발생했습니다.

기존 방식:

Dockerfile:

COPY id_rsa /root/.ssh/

문제:

• SSH Key가 이미지에 포함될 위험
• 보안 문제 발생

SSH 방식 적용:

docker-bake.hcl:

target "app" {

  ssh = [
    "default"
  ]

}

Dockerfile:

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

결과:

• Repository 정상 접근
• SSH Key 미저장
• 안전한 Docker 이미지 생성

Docker Buildx Bake SSH 사용 시 주의사항

첫 번째는 SSH Key를 Dockerfile에 직접 복사하지 않아야 합니다.

두 번째는 SSH Agent가 실행 중인지 확인해야 합니다.

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

네 번째는 빌드 로그에 인증 정보가 출력되지 않도록 해야 합니다.

Best Practice

Docker Buildx Bake SSH 활용 방법:

• Private Repository 접근 시 사용
• SSH Key 직접 복사 금지
• SSH Agent 활용
• CI/CD Secret 관리 사용
• BuildKit SSH Mount 사용
• 빌드 후 Key 존재 여부 확인

자주 묻는 질문

Docker Buildx Bake SSH는 무엇인가요?

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

SSH Key가 이미지에 저장되나요?

아닙니다.

빌드 과정에서만 사용되고 최종 이미지에는 포함되지 않습니다.

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

가능합니다.

SSH 인증을 통해 Private Repository Clone을 수행할 수 있습니다.

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

SSH는 Git이나 SSH 인증용이고, Secret은 비밀번호·Token 같은 일반 민감 정보 관리용입니다.

마무리

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

SSH Key를 Docker 이미지 내부에 복사하지 않고 빌드 과정에서만 사용할 수 있기 때문에 보안성을 유지하면서 필요한 소스 코드와 패키지를 가져올 수 있습니다.

특히 기업 환경이나 CI/CD 자동화 환경에서는 SSH Forwarding 방식을 활용하면 안전하고 효율적인 Docker 이미지 빌드 시스템을 구축할 수 있습니다.