Docker 프로젝트가 커질수록 Docker Hub 같은 공개 Registry만으로는 관리가 어려워지는 경우가 있습니다.

기업 환경이나 내부 서버에서는 보안과 관리 편의를 위해 Private Docker Registry를 사용하는 경우가 많습니다.

예:

• 회사 내부 Docker Registry
• Harbor Registry
• AWS ECR
• Google Artifact Registry
• Azure Container Registry
• 사설 서버 Registry

기본 흐름:

코드 작성

↓

Docker Buildx Bake 실행

↓

Docker Image 생성

↓

Private Registry Push

↓

서버에서 Pull

↓

Container 실행

Docker Buildx Bake를 사용하면 Private Registry에 맞는 Image Build와 Push 과정을 자동화할 수 있습니다.

예:

docker-bake.hcl

target "app" {

  tags = [
    "registry.example.com/app:v1"
  ]

}

실행:

docker buildx bake app --push

결과:

Docker Image 생성

↓

Private Registry 저장

이번 글에서는 Docker Buildx Bake Registry 설정 방법, Private Registry Login, Image Push, Cache 활용, 인증 관리, CI/CD 자동화까지 자세히 알아보겠습니다.

Docker Buildx Bake Registry란 무엇인가?

Docker Buildx Bake Registry는 Buildx Bake로 생성한 Docker 이미지를 Docker Registry에 저장하는 방식입니다.

구조:

Docker Buildx Bake

↓

Docker Image Build

↓

Registry 저장

↓

Container 배포

Registry는 Docker Image를 보관하고 여러 서버에서 사용할 수 있도록 제공하는 저장소입니다.

Docker Registry를 사용하는 이유

로컬 환경:

개발자 PC

↓

Docker Image 저장

문제:

• 서버 공유 어려움
• 팀 협업 제한
• 보안 관리 부족

Private Registry:

Docker Image

↓

Private Registry

↓

권한 있는 서버만 접근

장점:

• 이미지 보안 관리
• 내부 서비스 보호
• 버전 관리
• 배포 자동화

Docker Buildx Bake Registry 기본 설정

docker-bake.hcl:

target "app" {

  context = "."

  dockerfile = "Dockerfile"

  tags = [
    "registry.example.com/app:v1"
  ]

}

빌드:

docker buildx bake app --push

동작:

Dockerfile

↓

Image Build

↓

Registry Push

Docker Registry Login 설정

Private Registry에 Push하려면 인증이 필요합니다.

기본 로그인:

docker login registry.example.com

입력:

Username:

Password:

성공:

Login Succeeded

이후 Push가 가능합니다.

Docker Buildx Bake Private Registry Push

예:

docker-bake.hcl

target "production" {

  tags = [
    "registry.example.com/company/app:v1"
  ]

  output = [
    "type=registry"
  ]

}

실행:

docker buildx bake production --push

결과:

registry.example.com

↓

company/app:v1 저장

Docker Buildx Bake Registry Tag 관리 방법

Registry에서는 Tag 관리가 중요합니다.

예:

개발:

app:dev

테스트:

app:test

운영:

app:v1.0.0

권장:

app:2026-07-28

app:v1.0.0

app:stable

운영 환경에서는 latest만 사용하는 방식은 피하는 것이 좋습니다.

Docker Buildx Bake Registry Cache 사용

Private Registry는 Docker Build Cache 저장소로도 활용할 수 있습니다.

docker-bake.hcl:

target "app" {

  cache-from = [
    "type=registry,ref=registry.example.com/app:cache"
  ]

  cache-to = [
    "type=registry,ref=registry.example.com/app:cache,mode=max"
  ]

}

효과:

• Build Layer 재사용
• CI 속도 향상
• 반복 빌드 시간 감소

Docker Buildx Bake Registry Multi-platform 설정

Private Registry에서도 Multi-platform Image를 저장할 수 있습니다.

docker-bake.hcl:

target "app" {

  platforms = [
    "linux/amd64",
    "linux/arm64"
  ]

  tags = [
    "registry.example.com/app:v1"
  ]

}

실행:

docker buildx bake app --push

결과:

app:v1

├── linux/amd64

└── linux/arm64

서버 CPU 환경에 맞는 Image를 자동 선택합니다.

Docker Buildx Bake Harbor Registry 활용

Harbor는 기업 환경에서 많이 사용하는 Private Registry입니다.

구조:

Developer

↓

Docker Buildx Bake

↓

Harbor Registry

↓

Kubernetes

설정:

target "app" {

  tags = [
    "harbor.company.com/project/app:v1"
  ]

}

Push:

docker buildx bake --push

내부 Kubernetes 환경에서도 활용할 수 있습니다.

Docker Buildx Bake AWS ECR Registry 활용

AWS 환경에서는 ECR을 사용할 수 있습니다.

로그인:

aws ecr get-login-password | docker login

Tag:

target "app" {

  tags = [
    "123456789.dkr.ecr.region.amazonaws.com/app:v1"
  ]

}

Build:

docker buildx bake app --push

AWS Cloud 환경에서 자동 배포가 가능합니다.

Docker Buildx Bake CI/CD Registry 자동화

GitHub Actions 예:

- name: Login Registry

  uses: docker/login-action@v3


- name: Build Push

  run: |

    docker buildx bake --push

전체 흐름:

Code Push

↓

CI 실행

↓

Buildx Bake

↓

Registry Push

↓

Server Deploy

자동 Image 배포 환경을 만들 수 있습니다.

Docker Buildx Bake Registry Secret 관리

Registry 비밀번호는 파일에 직접 저장하면 안 됩니다.

잘못된 방식:

password = "123456"

권장:

• GitHub Secret
• GitLab Variables
• Jenkins Credentials
• Kubernetes Secret

보안 정보를 안전하게 관리할 수 있습니다.

Docker Buildx Bake Registry 실무 예제

프로젝트 구조:

project/

├── Dockerfile

├── docker-bake.hcl

└── deployment.yaml

docker-bake.hcl:

target "production" {

  tags = [
    "registry.company.com/app:v1.0.0"
  ]

  platforms = [
    "linux/amd64",
    "linux/arm64"
  ]

  cache-from = [
    "type=registry,ref=registry.company.com/app:cache"
  ]

  cache-to = [
    "type=registry,ref=registry.company.com/app:cache,mode=max"
  ]

}

실행:

docker buildx bake production --push

결과:

Image Build

↓

Registry 저장

↓

Kubernetes 배포 가능

Docker Buildx Bake Registry 문제 해결

Push 권한 오류

오류:

denied: requested access

확인:

• Registry Login 여부
• Repository 권한
• Image Tag 확인

인증 오류

확인:

docker login registry.example.com

다시 로그인 후 실행합니다.

Image Pull 실패

확인:

• Registry 주소
• Image Tag
• 서버 인증 설정

Docker Buildx Bake Registry 사용 시 주의사항

첫 번째는 Registry 인증 정보를 안전하게 관리해야 합니다.

두 번째는 운영 Image Tag 규칙을 정해야 합니다.

세 번째는 Cache Image와 Production Image를 분리하는 것이 좋습니다.

네 번째는 Private Registry 백업 정책이 필요합니다.

Best Practice

Docker Buildx Bake Registry 활용 방법:

• Private Registry 사용
• 버전 Tag 관리
• Registry Cache 적용
• Secret 관리
• Multi-platform Build 활용
• CI/CD 자동 Push 구성

자주 묻는 질문

Docker Buildx Bake로 Private Registry Push가 가능한가요?

가능합니다.

Registry Login 후 --push 옵션으로 저장할 수 있습니다.

Docker Hub 외 다른 Registry도 사용할 수 있나요?

가능합니다.

Harbor, ECR, ACR 등 대부분의 OCI Registry를 사용할 수 있습니다.

Registry를 Cache 저장소로 사용할 수 있나요?

가능합니다.

Docker Build Cache를 Registry에 저장하고 재사용할 수 있습니다.

Kubernetes와 함께 사용할 수 있나요?

가능합니다.

Registry에 저장한 Image를 Kubernetes Deployment에서 사용할 수 있습니다.

마무리

Docker Buildx Bake Registry는 Docker 이미지를 안전하게 관리하고 자동 배포하기 위한 핵심 기능입니다.

Private Registry를 활용하면 기업 환경에서도 Image 보안, 버전 관리, CI/CD 자동화, Kubernetes 배포까지 효율적으로 운영할 수 있습니다.

특히 Docker Buildx Bake의 Cache, Multi-platform, 자동 Push 기능과 Registry를 함께 사용하면 대규모 서버 환경에서도 안정적인 Docker Image 관리 시스템을 구축할 수 있습니다.