Docker 이미지를 운영 환경에 배포하는 과정에서 자동화는 매우 중요합니다.

코드 변경 후 매번 직접 Docker 이미지를 빌드하고 Registry에 Push하는 방식은 시간이 오래 걸리고 실수가 발생할 수 있습니다.

기존 방식:

docker buildx bake --push

직접 실행

↓

이미지 생성

↓

Registry 업로드

하지만 CI/CD 환경을 구성하면 다음 과정을 자동화할 수 있습니다.

코드 Push

↓

GitLab CI 실행

↓

Docker Buildx Bake 실행

↓

Docker Image 생성

↓

Registry Push

GitLab CI와 Docker Buildx Bake를 함께 사용하면 안정적인 Docker 이미지 자동 빌드 환경을 구축할 수 있습니다.

이번 글에서는 Docker Buildx Bake와 GitLab CI 연동 방법, Runner 설정, Registry Push, Cache 적용, Multi-platform 빌드 자동화 방법까지 자세히 알아보겠습니다.

Docker Buildx Bake GitLab CI란 무엇인가?

Docker Buildx Bake GitLab CI는 GitLab CI/CD Pipeline에서 Docker Buildx Bake를 자동 실행하는 방식입니다.

기본 구조:

GitLab Repository

↓

.gitlab-ci.yml 실행

↓

Docker Buildx 설정

↓

docker buildx bake 실행

↓

Image Push

코드 변경부터 Docker 이미지 배포까지 자동화할 수 있습니다.

Docker Buildx Bake와 GitLab CI를 사용하는 이유

수동 Build 방식:

docker buildx bake --push

문제:

• 개발자가 직접 실행 필요
• 환경마다 설정 차이 발생
• 반복 작업 증가
• 배포 속도 저하

GitLab CI 적용:

개발자 코드 Push

↓

자동 Build

↓

자동 Push

↓

자동 배포

장점:

• 빌드 자동화
• 동일한 환경 유지
• 배포 과정 단순화
• 작업 오류 감소

GitLab CI 기본 Docker Buildx 설정

GitLab Pipeline 파일:

.gitlab-ci.yml

기본 구조:

stages:

  - build


build-image:

  stage: build

  script:

    - docker buildx bake

GitLab Runner에서 Docker Buildx Bake를 실행합니다.

Docker Buildx Bake GitLab CI Runner 설정

Docker Buildx를 사용하려면 Runner 환경이 필요합니다.

일반적으로 사용하는 방식:

• Docker Executor
• Docker-in-Docker(DinD)

예:

image:
  docker:latest


services:
  - docker:dind

Docker 환경을 Pipeline 내부에서 사용할 수 있습니다.

GitLab CI에서 Docker Buildx 활성화하기

예제:

build-image:

  image:
    docker:latest

  services:
    - docker:dind

  script:

    - docker buildx create --use

    - docker buildx inspect

    - docker buildx bake

동작:

Docker 실행

↓

Buildx Builder 생성

↓

Bake 실행

Docker Buildx Bake GitLab CI Registry Push 설정

운영 환경에서는 생성한 이미지를 Registry에 저장해야 합니다.

GitLab Container Registry 사용:

login:

  script:

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

Build Push:

build:

  script:

    - docker buildx bake --push

결과:

Docker Build

↓

GitLab Container Registry 저장

Docker Buildx Bake GitLab CI Cache 설정

CI 환경에서는 매번 새로운 Runner가 실행되기 때문에 Cache 설정이 중요합니다.

docker-bake.hcl:

target "app" {

  cache-from = [

    "type=registry,ref=company/cache"

  ]


  cache-to = [

    "type=registry,ref=company/cache"

  ]

}

효과:

• Layer 재사용
• 빌드 시간 감소
• Runner 초기화 문제 해결

Docker Buildx Bake GitLab CI Multi-platform 빌드

여러 서버 환경을 지원하려면 Multi-platform 빌드가 필요합니다.

docker-bake.hcl:

target "app" {

  platforms = [

    "linux/amd64",

    "linux/arm64"

  ]

}

.gitlab-ci.yml:

build:

  script:

    - docker buildx bake --push

결과:

linux/amd64 이미지

+

linux/arm64 이미지

하나의 이미지 Tag로 여러 환경을 지원할 수 있습니다.

Docker Buildx Bake GitLab CI Secret 관리

민감한 정보는 GitLab CI Variables를 사용합니다.

예:

GitLab Variables:

DOCKER_PASSWORD

API_TOKEN

SSH_KEY

Pipeline:

variables:

  TOKEN: $API_TOKEN

Bake:

target "app" {

  secret = [

    "id=token,env=TOKEN"

  ]

}

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

Docker Buildx Bake GitLab CI 실무 예제

프로젝트 구조:

project/

├── Dockerfile

├── docker-bake.hcl

└── .gitlab-ci.yml

.gitlab-ci.yml:

stages:

  - build


docker-build:

  stage: build

  image:
    docker:latest


  services:

    - docker:dind


  script:

    - docker buildx create --use

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

    - docker buildx bake --push

코드 Push 시:

자동 Build

↓

자동 Push

Docker Buildx Bake GitLab CI Branch별 관리

환경별 Pipeline을 분리할 수 있습니다.

개발 Branch:

develop:

  script:

    - docker buildx bake dev

운영 Branch:

main:

  script:

    - docker buildx bake production

효과:

• 개발 환경 분리
• 운영 배포 보호
• 안정적인 릴리즈 관리

Docker Buildx Bake GitLab CI와 Deploy 자동화

전체 흐름:

Code Push

↓

GitLab CI 실행

↓

Docker Buildx Bake

↓

Registry Push

↓

Server Deploy

활용:

• Kubernetes 배포
• Docker Compose 배포
• Cloud 서버 운영

Linux 서버 문제 해결

기존에는 개발자가 직접 서버에서 Docker 이미지를 빌드했습니다.

기존:

docker buildx bake --push

문제:

• 빌드 시간 증가
• 작업 반복
• 환경 차이 발생

GitLab CI 적용:

script:

  - docker buildx bake --push

결과:

• 코드 Push 자동 Build
• 자동 Image Push
• 동일한 Build 환경 유지

배포 과정을 자동화할 수 있었습니다.

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

첫 번째는 GitLab Runner에 Docker 환경이 준비되어 있어야 합니다.

두 번째는 Registry 인증 정보를 CI Variables로 관리해야 합니다.

세 번째는 Cache 설정을 적용하면 빌드 속도가 향상됩니다.

네 번째는 운영 Branch 배포 조건을 설정하는 것이 좋습니다.

Best Practice

Docker Buildx Bake GitLab CI 활용 방법:

• docker-bake.hcl 중앙 관리
• GitLab CI Variables 활용
• Registry Push 자동화
• Cache 적용
• Multi-platform 빌드 구성
• Production Pipeline 분리

자주 묻는 질문

Docker Buildx Bake를 GitLab CI에서 사용할 수 있나요?

가능합니다.

.gitlab-ci.yml에서 Docker Buildx Bake 명령을 실행하면 됩니다.

GitLab Registry에 자동 Push할 수 있나요?

가능합니다.

GitLab CI Variables를 이용해 인증 후 --push 옵션을 사용할 수 있습니다.

Cache를 적용할 수 있나요?

가능합니다.

Registry Cache 또는 GitLab Cache를 활용할 수 있습니다.

Multi-platform 빌드가 가능한가요?

가능합니다.

linux/amd64와 linux/arm64 이미지를 동시에 생성할 수 있습니다.

마무리

Docker Buildx Bake와 GitLab CI를 함께 사용하면 Docker 이미지 빌드와 배포 과정을 자동화할 수 있습니다.

코드 변경부터 이미지 생성, Registry Push까지 Pipeline으로 연결하여 반복적인 작업을 줄이고 안정적인 Docker 운영 환경을 구축할 수 있습니다.

특히 여러 서비스와 다양한 서버 환경을 운영하는 프로젝트에서는 GitLab CI와 Docker Buildx Bake를 활용하면 더욱 효율적인 CI/CD 시스템을 만들 수 있습니다.