Docker 이미지를 GitLab CI 환경에서 반복적으로 빌드하다 보면 가장 큰 문제는 빌드 시간 증가와 Runner 초기화 문제입니다.

GitLab Runner는 Pipeline 실행마다 새로운 환경에서 동작하는 경우가 많기 때문에 이전 Docker Build Cache를 그대로 사용할 수 없습니다.

예:

코드 변경

↓

GitLab CI 실행

↓

새로운 Runner 생성

↓

Docker Build 시작

↓

Package 설치 반복

↓

Image 생성

변경되지 않은 Layer까지 다시 생성하면 CI 시간이 길어지고 서버 비용도 증가합니다.

Docker Buildx Bake에서는 GitLab CI Cache와 Registry Cache를 활용하여 이전 Build 결과를 저장하고 재사용할 수 있습니다.

예:

docker-bake.hcl

target "app" {

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

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

}

이렇게 설정하면 이전 Docker Layer를 가져와 변경된 부분만 다시 Build할 수 있습니다.

이번 글에서는 Docker Buildx Bake GitLab CI Cache의 개념부터 Cache 설정 방법, Registry Cache 활용, GitLab Pipeline 최적화, Multi-platform 빌드 적용까지 자세히 알아보겠습니다.

Docker Buildx Bake GitLab CI Cache란 무엇인가?

Docker Buildx Bake GitLab CI Cache는 GitLab Pipeline에서 Docker Build Cache를 저장하고 재사용하는 기능입니다.

기본 흐름:

Docker Build

↓

Layer Cache 생성

↓

Cache 저장

↓

다음 Pipeline 실행

↓

Cache 재사용

↓

빠른 Build

Docker 이미지는 여러 Layer로 구성됩니다.

예:

Base Image Layer

↓

Package 설치 Layer

↓

Application Layer

↓

Final Image

변경되지 않은 Layer는 다시 만들 필요 없이 재사용할 수 있습니다.

Docker Buildx Bake GitLab CI Cache가 필요한 이유

Cache가 없는 경우:

docker buildx bake --push

실행할 때마다:

Base Image 다운로드

↓

Dependency 설치

↓

Source Build

↓

Image 생성

반복됩니다.

문제:

• Pipeline 실행 시간 증가
• Runner 리소스 낭비
• 개발 속도 저하
• CI 비용 증가

Cache 적용:

기존 Layer 확인

↓

변경 없는 Layer 재사용

↓

변경된 부분만 Build

장점:

• Build 시간 단축
• Pipeline 효율 향상
• Registry 부하 감소

Docker Buildx Bake GitLab CI Cache 기본 설정

가장 많이 사용하는 방식은 Registry 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"
  ]

}

동작:

Registry Cache 확인

↓

기존 Layer 다운로드

↓

Docker Build

↓

새로운 Cache 저장

GitLab CI Pipeline Cache 설정하기

.gitlab-ci.yml:

stages:

  - build


docker-build:

  stage: build

  image:
    docker:latest

  services:

    - docker:dind


  script:

    - docker buildx create --use

    - docker buildx bake --push

실행 과정:

GitLab Runner 실행

↓

Buildx Builder 생성

↓

Cache Load

↓

Image Build

↓

Cache 저장

Docker Buildx Bake Registry Cache 사용법

운영 환경에서는 Registry Cache 방식이 가장 안정적입니다.

예:

target "production" {

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

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

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

}

mode=max 사용 시 더 많은 Build Layer를 저장합니다.

장점:

• 높은 Cache 재사용률
• 여러 Runner 공유 가능
• 대규모 프로젝트 적합

Docker Buildx Bake GitLab CI Cache Mode 설정

Cache Mode는 저장할 Layer 범위를 결정합니다.

mode=min

cache-to = [
  "type=registry,ref=company/cache,mode=min"
]

특징:

• 저장 용량 감소
• 기본 결과 중심
• 관리 쉬움

mode=max

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

특징:

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

비교:

방식	특징
mode=min	용량 절약
mode=max	빌드 속도 최적화

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

Docker Buildx Bake GitLab CI Cache와 Multi-platform 빌드

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

docker-bake.hcl:

target "app" {

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

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

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

}

결과:

linux/amd64 Build

↓

Cache 저장


linux/arm64 Build

↓

Cache 저장

다음 Pipeline에서 재사용됩니다.

Docker Buildx Bake GitLab CI Cache와 Private Registry 활용

Private Registry를 사용하는 경우 먼저 로그인해야 합니다.

.gitlab-ci.yml:

before_script:

  - docker login
      -u $CI_REGISTRY_USER
      -p $CI_REGISTRY_PASSWORD
      $CI_REGISTRY

Build:

script:

  - docker buildx bake --push

흐름:

Registry Login

↓

Cache Pull

↓

Build

↓

Cache Push

↓

Image Push

Docker Buildx Bake GitLab CI Cache 실무 예제

프로젝트 구조:

project/

├── Dockerfile

├── docker-bake.hcl

└── .gitlab-ci.yml

docker-bake.hcl:

target "production" {

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

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

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

}

.gitlab-ci.yml:

build:

  stage: build

  script:

    - docker buildx create --use

    - docker buildx bake production --push

결과:

첫 번째 Build

↓

전체 Layer 생성


두 번째 Build

↓

기존 Layer 재사용

Docker Buildx Bake GitLab CI Cache 문제 해결

Cache가 적용되지 않는 경우

Builder 확인:

docker buildx ls

Build 로그 확인:

CACHED

표시가 있는지 확인합니다.

Registry Cache 접근 오류

확인:

• Registry 로그인 상태
• Cache Image 권한
• Repository 존재 여부

Cache 충돌 문제

프로젝트별 Cache 이름을 분리합니다.

예:

company/backend:cache

company/frontend:cache

Docker Buildx Bake GitLab CI Cache 사용 시 주의사항

첫 번째는 Cache 저장 위치를 명확하게 관리해야 합니다.

두 번째는 여러 프로젝트가 같은 Cache를 공유하지 않도록 해야 합니다.

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

네 번째는 오래된 Cache 정리 정책이 필요합니다.

Best Practice

Docker Buildx Bake GitLab CI Cache 활용 방법:

• Registry Cache 사용
• cache-from과 cache-to 함께 설정
• Production은 mode=max 활용
• Project별 Cache 분리
• Multi-platform과 함께 사용
• Build 로그 확인

자주 묻는 질문

Docker Buildx Bake GitLab CI Cache는 무엇인가요?

GitLab CI 환경에서 Docker Build Cache를 저장하고 재사용하는 기능입니다.

GitLab Runner가 새로 생성되어도 Cache 사용이 가능한가요?

가능합니다.

Registry Cache를 사용하면 다른 Runner에서도 Cache를 가져올 수 있습니다.

GitLab Cache와 Docker Build Cache는 같은 것인가요?

아닙니다.

GitLab Cache는 Pipeline 파일이나 데이터를 저장하고, Docker Build Cache는 이미지 Layer를 저장합니다.

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

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

마무리

Docker Buildx Bake GitLab CI Cache는 반복적인 Docker 이미지 빌드 시간을 줄이는 핵심 기능입니다.

GitLab Runner가 새롭게 생성되는 환경에서도 Registry Cache를 활용하면 기존 Docker Layer를 재사용할 수 있어 빠르고 효율적인 CI/CD Pipeline을 구축할 수 있습니다.

특히 Multi-platform Build, Private Registry, 자동 배포 환경에서는 Docker Buildx Bake Cache 설정을 함께 적용하면 안정적인 Docker 이미지 빌드 시스템을 운영할 수 있습니다.