Docker Image를 반복적으로 빌드하는 환경에서는 Build Cache 관리가 매우 중요합니다.

특히 CI/CD 환경에서는 매번 새로운 Runner가 생성되기 때문에 기존 Build Cache를 그대로 사용할 수 없습니다.

예:

코드 변경

↓

CI 실행

↓

Docker Build 시작

↓

기존 Layer 없음

↓

전체 다시 Build

이 과정은 빌드 시간을 증가시키고 서버 자원을 많이 사용합니다.

Docker Buildx Bake에서는 cache-to 옵션을 사용하여 생성된 Build Cache를 원하는 위치에 저장할 수 있습니다.

예:

docker-bake.hcl

target "app" {

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

}

실행:

docker buildx bake app

결과:

Docker Build

↓

Cache 생성

↓

Registry 저장

다음 Build에서는 저장된 Cache를 다시 사용할 수 있습니다.

이번 글에서는 Docker Buildx Bake Cache-to의 개념부터 Cache 저장 위치, mode 설정, Registry Cache, CI/CD 활용 방법까지 자세히 알아보겠습니다.

Docker Buildx Bake Cache-to란 무엇인가?

Docker Buildx Bake Cache-to는 Docker Build 과정에서 생성된 Cache Layer를 외부 저장소로 내보내는 기능입니다.

기본 구조:

Docker Build

↓

Build Layer 생성

↓

Cache Export

↓

외부 저장소 저장

저장 가능한 위치:

• Registry
• Local Directory
• GitHub Actions Cache
• Inline Cache
• Local Cache

Docker Buildx Bake Cache-to가 필요한 이유

기본 Docker Build Cache:

개발자 PC

↓

로컬 저장

문제:

• 다른 서버에서 사용 불가
• CI Runner 공유 불가
• Build 환경 변경 시 Cache 손실

Cache-to 사용:

Docker Build

↓

Cache 저장

↓

다음 Build

↓

Cache 재사용

장점:

• Build 속도 향상
• CI 비용 절감
• 반복 작업 감소
• 서버 자원 절약

Docker Buildx Bake Cache-to 기본 설정

docker-bake.hcl:

target "app" {

  cache-to = [
    "type=registry,ref=company/app:cache"
  ]

}

동작:

Image Build

↓

Cache Layer 생성

↓

Registry Push

Docker Buildx Bake Cache-to 타입 종류

type=registry

Registry에 Cache 저장

예:

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

특징:

• 여러 서버 공유 가능
• CI/CD 환경 적합
• 가장 많이 사용

---

type=local

로컬 폴더에 Cache 저장

예:

cache-to = [
  "type=local,dest=./cache"
]

결과:

cache/

├── index.json

├── blobs

└── metadata

활용:

• 개발 환경
• 테스트 환경

---

type=gha

GitHub Actions Cache 저장

예:

cache-to = [
  "type=gha"
]

활용:

• GitHub Actions CI

---

type=inline

Image 내부에 Cache Metadata 저장

예:

cache-to = [
  "type=inline"
]

특징:

• 설정 간단
• Image와 함께 관리

Docker Buildx Bake Cache-to mode 설정

Cache 저장 방식은 mode 옵션으로 변경할 수 있습니다.

mode=min

cache-to = [
  "type=registry,ref=app:cache,mode=min"
]

특징:

• 최소 Cache 저장
• 저장 공간 절약
• 빠른 관리

---

mode=max

cache-to = [
  "type=registry,ref=app:cache,mode=max"
]

특징:

• 모든 Layer 저장
• Cache 재사용률 증가
• 빠른 재빌드

비교:

설정	특징
mode=min	용량 절약
mode=max	최대 성능

CI/CD 환경에서는 보통 mode=max를 사용합니다.

Docker Buildx Bake Cache-to와 Cache-from 함께 사용하기

Cache-to는 저장 기능이고 Cache-from은 가져오는 기능입니다.

함께 사용:

target "app" {

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

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

}

흐름:

기존 Cache 가져오기

↓

Docker Build

↓

새 Cache 저장

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

Docker Buildx Bake Cache-to Registry 활용

Private Registry:

target "production" {

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

}

결과:

Registry

├── app:v1

└── app:cache

Image와 Cache를 분리하여 관리할 수 있습니다.

Docker Buildx Bake Cache-to GitHub Actions 활용

GitHub Actions:

- name: Build

  run: |

    docker buildx bake app

Bake:

target "app" {

  cache-from = [
    "type=gha"
  ]

  cache-to = [
    "type=gha,mode=max"
  ]

}

동작:

GitHub Runner

↓

Cache 복원

↓

Build

↓

Cache 저장

Docker Buildx Bake Cache-to Multi-platform 활용

Multi-platform Build에서도 Cache를 사용할 수 있습니다.

예:

target "app" {

  platforms = [

    "linux/amd64",

    "linux/arm64"

  ]

  cache-to = [

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

  ]

}

결과:

Cache

├── amd64 Layer

└── arm64 Layer

Docker Buildx Bake Cache-to 실무 예제

프로젝트:

project/

├── Dockerfile

├── docker-bake.hcl

└── .gitlab-ci.yml

docker-bake.hcl:

target "production" {

  tags = [

    "registry.company.com/app:v1"

  ]


  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

결과:

첫 번째 Build

↓

전체 Layer 생성


두 번째 Build

↓

Cache 재사용

↓

빠른 Build

Docker Buildx Bake Cache-to 문제 해결

Cache가 저장되지 않는 경우

확인:

docker buildx ls

Builder 상태를 확인합니다.

Registry Cache Push 오류

확인:

docker login

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

Cache 용량 증가 문제

해결:

mode=min

사용하거나 오래된 Cache를 정리합니다.

Docker Buildx Bake Cache-to 사용 시 주의사항

첫 번째는 Cache 저장 위치를 목적에 맞게 선택해야 합니다.

두 번째는 Production 환경에서는 Cache와 Image 저장소를 분리하는 것이 좋습니다.

세 번째는 민감한 정보가 Cache에 포함되지 않도록 해야 합니다.

네 번째는 주기적인 Cache 정리가 필요합니다.

Best Practice

Docker Buildx Bake Cache-to 활용 방법:

• Registry Cache 사용
• cache-from과 함께 구성
• CI/CD 자동화 연결
• Production은 mode=max 활용
• Cache 저장소 분리
• 정기적인 Cache 관리

자주 묻는 질문

Docker Buildx Bake Cache-to는 무엇인가요?

Docker Build 과정에서 생성된 Cache를 외부 저장소로 저장하는 기능입니다.

Cache-to와 Cache-from 차이는 무엇인가요?

Cache-to는 저장, Cache-from은 불러오기 기능입니다.

가장 추천하는 Cache 저장 방식은 무엇인가요?

운영 환경에서는 Registry Cache 방식이 가장 많이 사용됩니다.

Build 속도가 빨라지나요?

가능합니다.

기존 Layer를 재사용하기 때문에 반복 Build 시간이 줄어듭니다.

마무리

Docker Buildx Bake Cache-to는 Docker Build 속도를 최적화하기 위한 핵심 기능입니다.

생성된 Build Cache를 Registry, GitHub Actions Cache, Local Storage 등에 저장하고 다음 Build에서 재사용할 수 있어 반복적인 Image 생성 시간을 크게 줄일 수 있습니다.

특히 CI/CD, Multi-platform Build, Private Registry 환경에서는 Cache-to와 Cache-from을 함께 구성하면 빠르고 안정적인 Docker Build 시스템을 구축할 수 있습니다.