Docker 프로젝트를 운영하다 보면 하나의 이미지라도 여러 가지 조건으로 빌드해야 하는 경우가 많습니다.

예:

• 여러 운영체제 버전
• 여러 CPU 아키텍처
• 여러 Node.js 버전
• 여러 환경 설정
• 여러 이미지 Variant

기존 방식에서는 각각의 조합마다 Build 명령어를 따로 실행해야 합니다.

예:

docker buildx build \
--platform linux/amd64 \
--build-arg VERSION=18 .

docker buildx build \
--platform linux/arm64 \
--build-arg VERSION=20 .

빌드 조합이 많아질수록 명령어 관리가 복잡해집니다.

Docker Buildx Bake에서는 Matrix 기능을 사용하여 여러 빌드 조합을 자동으로 생성하고 관리할 수 있습니다.

예:

target "app" {

  matrix = {
    platform = [
      "linux/amd64",
      "linux/arm64"
    ]
  }

}

하나의 Target 설정으로 여러 빌드를 자동 생성할 수 있습니다.

이번 글에서는 Docker Buildx Bake Matrix의 개념부터 기본 사용법, 플랫폼 조합, 환경별 빌드 자동화, CI/CD 활용 방법까지 자세히 알아보겠습니다.

Docker Buildx Bake Matrix란 무엇인가?

Docker Buildx Bake Matrix는 하나의 Target에서 여러 빌드 조합을 자동으로 생성하는 기능입니다.

기본 구조:

Matrix 설정

↓

여러 Target 자동 생성

↓

Docker 이미지 빌드

예:

app

↓

linux/amd64

linux/arm64

↓

각각 이미지 생성

반복적인 Target 작성 없이 다양한 빌드 환경을 관리할 수 있습니다.

Docker Buildx Bake Matrix가 필요한 이유

Matrix를 사용하지 않는 경우:

target "app-amd64" {

  platforms = [
    "linux/amd64"
  ]

}


target "app-arm64" {

  platforms = [
    "linux/arm64"
  ]

}

문제:

• Target 증가
• 설정 반복
• 관리 어려움

Matrix 사용:

target "app" {

  matrix = {
    platform = [
      "linux/amd64",
      "linux/arm64"
    ]
  }

}

장점:

• 반복 설정 제거
• 빌드 조합 자동 생성
• 유지보수 편리

Docker Buildx Bake Matrix 기본 사용법

docker-bake.hcl

target "app" {

  matrix = {

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

  }

  platforms = [
    "${platform}"
  ]

  tags = [
    "company/app:${platform}"
  ]

}

실행:

docker buildx bake app

결과:

app linux/amd64 빌드

app linux/arm64 빌드

자동으로 여러 빌드가 생성됩니다.

Docker Buildx Bake Matrix와 변수 활용하기

Matrix는 변수와 함께 사용하면 더욱 강력합니다.

예:

variable "NODE_VERSION" {

  default = [
    "18",
    "20"
  ]

}


target "app" {

  matrix = {

    node = NODE_VERSION

  }

}

결과:

Node 18 빌드

Node 20 빌드

여러 버전을 자동 테스트할 수 있습니다.

Docker Buildx Bake Matrix 여러 조합 만들기

여러 값을 조합할 수 있습니다.

예:

target "app" {

  matrix = {

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

    environment = [
      "dev",
      "production"
    ]

  }

}

생성:

linux/amd64 + dev

linux/amd64 + production

linux/arm64 + dev

linux/arm64 + production

총 4개의 빌드 조합이 만들어집니다.

Docker Buildx Bake Matrix와 Tag 자동 생성

Matrix 값을 Tag에 활용할 수 있습니다.

예:

target "app" {

  matrix = {

    version = [
      "v1",
      "v2"
    ]

  }

  tags = [

    "company/app:${version}"

  ]

}

결과:

company/app:v1

company/app:v2

버전별 이미지를 자동 생성할 수 있습니다.

Docker Buildx Bake Matrix 실무 활용 예제

여러 Node.js 버전 테스트

프로젝트:

Node 18

Node 20

Node 22

Bake:

target "test" {

  matrix = {

    node = [
      "18",
      "20",
      "22"
    ]

  }

  args = {

    NODE_VERSION = "${node}"

  }

}

실행:

docker buildx bake test

결과:

Node 18 테스트

Node 20 테스트

Node 22 테스트

자동 테스트 환경을 만들 수 있습니다.

Docker Buildx Bake Matrix와 Multi-platform 빌드

Platform Matrix:

target "app" {

  matrix = {

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

  }

  platforms = [
    "${arch}"
  ]

}

결과:

Intel 이미지 생성

ARM 이미지 생성

멀티 아키텍처 빌드를 자동화할 수 있습니다.

CI/CD에서 Docker Buildx Bake Matrix 활용

CI 환경에서는 테스트 조합을 자동 생성할 수 있습니다.

예:

- name: Build Matrix
  run: |
    docker buildx bake

활용:

• 여러 플랫폼 테스트
• 여러 버전 테스트
• 자동 이미지 생성
• 배포 자동화

Docker Buildx Bake Matrix와 Cache 활용

여러 빌드를 실행하면 Cache 활용이 중요합니다.

예:

target "app" {

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

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

}

효과:

• 반복 Layer 재사용
• 빌드 시간 감소
• CI 비용 절감

Linux 서버 문제 해결

여러 서버 환경용 Docker 이미지를 각각 만들고 있었습니다.

기존:

docker buildx build --platform linux/amd64 .

docker buildx build --platform linux/arm64 .

문제:

• 명령어 반복
• 플랫폼 추가 시 관리 어려움
• CI 설정 복잡

Matrix 적용:

target "app" {

  matrix = {

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

  }

  platforms = [
    "${platform}"
  ]

}

실행:

docker buildx bake app

결과:

amd64 이미지 생성

arm64 이미지 생성

여러 환경 빌드를 자동화할 수 있었습니다.

Docker Buildx Bake Matrix 사용 시 주의사항

첫 번째는 Matrix 조합이 너무 많아지지 않도록 관리해야 합니다.

두 번째는 빌드 시간이 조합 수만큼 증가할 수 있습니다.

세 번째는 Cache 설정을 함께 사용하는 것이 좋습니다.

네 번째는 생성되는 Image Tag 규칙을 명확하게 정해야 합니다.

Best Practice

Docker Buildx Bake Matrix 활용 방법:

• 반복 빌드 자동화
• 플랫폼 조합 관리
• 버전별 테스트 구성
• CI/CD Pipeline 연결
• Cache 함께 사용
• Tag 규칙 통일

자주 묻는 질문

Docker Buildx Bake Matrix는 무엇인가요?

하나의 Target에서 여러 빌드 조합을 자동으로 생성하는 기능입니다.

어떤 경우에 사용하면 좋은가요?

여러 플랫폼, 버전, 환경을 동시에 빌드해야 하는 경우 유용합니다.

여러 플랫폼 이미지를 만들 수 있나요?

가능합니다.

linux/amd64와 linux/arm64 같은 조합을 자동 생성할 수 있습니다.

작은 프로젝트에서도 사용할 수 있나요?

가능하지만 여러 환경을 관리하는 프로젝트에서 더 큰 효과를 얻을 수 있습니다.

마무리

Docker Buildx Bake Matrix는 반복적인 Docker 빌드 작업을 자동화하는 강력한 기능입니다.

여러 플랫폼, 버전, 환경 조합을 하나의 설정 파일로 관리할 수 있어 복잡한 빌드 과정을 단순화할 수 있습니다.

특히 멀티 플랫폼 이미지 제작, 여러 버전 테스트, CI/CD 자동화 환경에서는 Matrix 기능을 활용하면 개발 시간을 줄이고 안정적인 Docker 이미지 관리 환경을 구축할 수 있습니다.

Docker Buildx Bake Matrix와 Cache, Platform 기능을 함께 사용하면 더욱 효율적인 대규모 Docker 빌드 시스템을 운영할 수 있습니다.