Docker 이미지를 개발 환경에서만 사용하는 것이 아니라 여러 서버, 팀원, CI/CD 환경에서 사용하려면 이미지를 저장하고 공유할 수 있는 Registry가 필요합니다.

가장 많이 사용하는 Docker Registry 중 하나가 Docker Hub입니다.

기본 흐름:

Docker Image Build

↓

Docker Hub Push

↓

다른 서버 Pull

↓

Container 실행

Docker Buildx Bake를 활용하면 Docker Hub에 이미지를 자동으로 빌드하고 Push하는 작업을 설정 파일 기반으로 관리할 수 있습니다.

예:

docker-bake.hcl

target "app" {

  tags = [
    "username/app:v1"
  ]

  output = [
    "type=registry"
  ]

}

빌드:

docker buildx bake app --push

결과:

Docker Image

↓

Docker Hub 저장

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

Docker Buildx Bake Docker Hub란 무엇인가?

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

구조:

Docker Buildx Bake

↓

Docker Image 생성

↓

Docker Hub Registry

↓

Container 배포

Docker Hub는 Docker 이미지를 저장하고 공유하는 중앙 저장소 역할을 합니다.

Docker Hub를 사용하는 이유

로컬 Docker 환경:

내 컴퓨터

↓

Docker Image 저장

문제:

• 다른 서버에서 사용 어려움
• 팀 공유 불편
• 배포 자동화 어려움

Docker Hub 사용:

Docker Image

↓

Docker Hub

↓

어디서든 Pull 가능

장점:

• 이미지 중앙 관리
• 서버 간 공유 가능
• CI/CD 연동 가능
• 버전 관리 가능

Docker Hub Repository 생성하기

Docker Hub에서 Repository를 생성합니다.

예:

username/app

Image 이름 구조:

Docker Hub 사용자명/Repository명:Tag

예:

myuser/backend:v1

구성:

myuser

= Docker Hub 계정

backend

= Repository 이름

v1

= Image Version Tag

Docker Buildx Bake Docker Hub Login

Docker Hub에 Push하려면 인증이 필요합니다.

로그인:

docker login

입력:

Username:
Password:

성공:

Login Succeeded

CI/CD 환경에서는 Token 사용을 권장합니다.

Docker Buildx Bake Docker Hub 기본 설정

docker-bake.hcl:

target "app" {

  context = "."

  dockerfile = "Dockerfile"

  tags = [
    "myuser/app:v1"
  ]

  output = [
    "type=registry"
  ]

}

빌드:

docker buildx bake app --push

동작:

Dockerfile

↓

Image Build

↓

Docker Hub Push

Docker Buildx Bake Tag 관리 방법

Docker Image는 Tag를 통해 버전을 관리합니다.

예:

myuser/app:v1

myuser/app:v2

myuser/app:latest

권장 방식:

개발:

app:dev

테스트:

app:test

운영:

app:v1.0.0

버전 관리가 쉬워집니다.

Docker Buildx Bake Docker Hub Multi-platform Push

Docker Hub는 Multi-platform Image 저장을 지원합니다.

docker-bake.hcl:

target "app" {

  platforms = [

    "linux/amd64",

    "linux/arm64"

  ]

  tags = [

    "myuser/app:v1"

  ]

}

실행:

docker buildx bake app --push

결과:

myuser/app:v1

├── linux/amd64

└── linux/arm64

서버 환경에 맞는 이미지를 자동 선택합니다.

Docker Buildx Bake Docker Hub Cache 활용

Docker Hub Registry를 Cache 저장소로 활용할 수 있습니다.

docker-bake.hcl:

target "app" {

  cache-from = [

    "type=registry,ref=myuser/app:cache"

  ]

  cache-to = [

    "type=registry,ref=myuser/app:cache,mode=max"

  ]

}

효과:

• 기존 Layer 재사용
• Build 시간 감소
• CI/CD 속도 향상

Docker Buildx Bake Docker Hub Private Repository 사용

Private Repository도 사용할 수 있습니다.

Login:

docker login

설정:

target "private" {

  tags = [

    "myuser/private-app:v1"

  ]

}

Push:

docker buildx bake private --push

권한이 있는 사용자만 이미지를 사용할 수 있습니다.

Docker Buildx Bake Docker Hub CI/CD 활용

GitHub Actions 예:

name: Docker Build

on:

  push:

    branches:

      - main


jobs:

  build:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v4


      - uses: docker/setup-buildx-action@v3


      - uses: docker/login-action@v3

        with:

          username: ${{ secrets.DOCKER_USERNAME }}

          password: ${{ secrets.DOCKER_TOKEN }}


      - run:

          docker buildx bake --push

흐름:

Code Push

↓

GitHub Actions

↓

Buildx Bake

↓

Docker Hub Push

Docker Buildx Bake Docker Hub와 Kubernetes 활용

Docker Hub에 저장된 이미지는 Kubernetes에서 사용할 수 있습니다.

Deployment:

containers:

- name: app

  image: myuser/app:v1

배포:

kubectl apply -f deployment.yaml

Kubernetes가 Docker Hub에서 Image를 가져옵니다.

Docker Buildx Bake Docker Hub 실무 예제

프로젝트:

project/

├── Dockerfile

├── docker-bake.hcl

└── deployment.yaml

docker-bake.hcl:

target "production" {

  tags = [

    "myuser/company-app:v1"

  ]

  platforms = [

    "linux/amd64",

    "linux/arm64"

  ]

}

실행:

docker buildx bake production --push

결과:

Docker Hub

↓

company-app:v1 저장

↓

서버 배포 가능

Docker Buildx Bake Docker Hub 문제 해결

Push 권한 오류

오류:

denied: requested access to the resource is denied

확인:

• Docker Hub Login 상태
• Repository 이름
• Username 확인

Tag 오류

잘못된 예:

app:v1

올바른 예:

username/app:v1

Docker Hub는 사용자명이 포함되어야 합니다.

Multi-platform Push 실패

확인:

docker buildx ls

Builder가 정상인지 확인합니다.

Docker Buildx Bake Docker Hub 사용 시 주의사항

첫 번째는 Image Tag 규칙을 통일해야 합니다.

두 번째는 Docker Hub Token을 사용하는 것이 안전합니다.

세 번째는 Private Image 권한 관리를 해야 합니다.

네 번째는 운영 Image는 버전 Tag를 사용하는 것이 좋습니다.

Best Practice

Docker Buildx Bake Docker Hub 활용 방법:

• Repository 이름 규칙 설정
• Version Tag 관리
• Registry Cache 활용
• Multi-platform Push 사용
• CI/CD 자동화 연결
• Token 인증 사용

자주 묻는 질문

Docker Buildx Bake로 Docker Hub Push가 가능한가요?

가능합니다.

docker buildx bake --push 명령으로 자동 Push할 수 있습니다.

Docker Hub Private Repository도 사용할 수 있나요?

가능합니다.

Login 후 권한이 있는 Repository에 Push할 수 있습니다.

여러 플랫폼 이미지를 저장할 수 있나요?

가능합니다.

linux/amd64와 linux/arm64 Multi-platform Image를 저장할 수 있습니다.

Cache 저장도 가능한가요?

가능합니다.

Docker Hub Registry Cache를 활용할 수 있습니다.

마무리

Docker Buildx Bake와 Docker Hub를 함께 사용하면 Docker 이미지 생성부터 저장, 배포까지 효율적인 관리 환경을 구축할 수 있습니다.

Buildx Bake의 설정 파일 기반 관리 방식과 Docker Hub Registry를 결합하면 여러 서비스와 다양한 환경에서도 안정적인 Docker Image 운영이 가능합니다.

특히 CI/CD 자동화, Kubernetes 배포, Multi-platform 환경에서는 Docker Buildx Bake와 Docker Hub 조합이 매우 강력한 Docker 운영 방식이 됩니다.