Docker 프로젝트를 운영하다 보면 같은 이미지를 빌드하더라도 환경에 따라 다른 설정이 필요한 경우가 많습니다.

예:

• 개발 환경에서는 테스트용 설정 사용
• 스테이징 환경에서는 검증용 설정 사용
• 운영 환경에서는 최적화된 설정 사용
• CI/CD에서는 별도의 Cache 설정 적용

하지만 하나의 docker-bake.hcl 파일에 모든 환경 설정을 넣으면 관리가 복잡해질 수 있습니다.

예:

target "app" {

  tags = [
    "company/app:latest"
  ]

  platforms = [
    "linux/amd64"
  ]

}

운영 환경에서 Tag나 Platform을 변경하려면 기본 설정 파일을 수정해야 합니다.

이때 사용하는 기능이 바로 Docker Buildx Bake Override입니다.

Override를 사용하면 기본 Bake 설정은 유지하면서 특정 환경에서만 필요한 설정을 추가하거나 변경할 수 있습니다.

예:

기본 파일:

docker-bake.hcl

Override 파일:

docker-bake.override.hcl

실행:

docker buildx bake

자동으로 Override 설정이 적용됩니다.

이번 글에서는 Docker Buildx Bake Override의 개념부터 파일 구조, 환경별 설정 변경, CI/CD 활용 방법까지 자세히 알아보겠습니다.

Docker Buildx Bake Override란 무엇인가?

Docker Buildx Bake Override는 기존 Bake 설정을 덮어쓰거나 추가 변경하는 기능입니다.

기본 구조:

기본 Bake 파일

↓

Override 파일 적용

↓

최종 Build 설정 생성

예:

docker-bake.hcl

target "app" {

  tags = [
    "company/app:latest"
  ]

}

docker-bake.override.hcl

target "app" {

  tags = [
    "company/app:dev"
  ]

}

결과:

company/app:dev

기존 설정을 변경하여 사용할 수 있습니다.

Docker Buildx Bake Override가 필요한 이유

Override를 사용하지 않는 경우:

환경별 파일을 따로 관리해야 합니다.

예:

docker-bake-dev.hcl

docker-bake-stage.hcl

docker-bake-prod.hcl

문제:

• 설정 중복
• 수정 작업 증가
• 공통 설정 관리 어려움

Override 사용:

기본 설정:

docker-bake.hcl

환경별 변경:

docker-bake.override.hcl

장점:

• 공통 설정 유지
• 환경별 변경 가능
• 관리 파일 감소
• CI/CD 적용 편리

Docker Buildx Bake Override 파일 구조

Docker Buildx Bake는 다음 파일을 자동으로 읽습니다.

기본:

docker-bake.hcl

Override:

docker-bake.override.hcl

구조:

project/

├── docker-bake.hcl

└── docker-bake.override.hcl

실행:

docker buildx bake

기본 설정 후 Override 설정이 적용됩니다.

Docker Buildx Bake Override 기본 사용법

기본 파일:

docker-bake.hcl

target "app" {

  context = "."

  tags = [
    "company/app:latest"
  ]

}

Override 파일:

docker-bake.override.hcl

target "app" {

  tags = [
    "company/app:dev"
  ]

}

실행:

docker buildx bake

결과:

company/app:dev

Override 설정이 적용됩니다.

Docker Buildx Bake Override로 환경별 Tag 변경하기

개발 환경:

docker-bake.override.hcl

target "app" {

  tags = [
    "company/app:development"
  ]

}

운영 환경:

docker-bake.prod.hcl

target "app" {

  tags = [
    "company/app:production"
  ]

}

환경별로 다른 이미지를 생성할 수 있습니다.

Docker Buildx Bake Override와 -f 옵션 사용하기

특정 Override 파일을 사용할 수도 있습니다.

예:

docker-bake.production.hcl

실행:

docker buildx bake
-f docker-bake.hcl
-f docker-bake.production.hcl

여러 설정 파일을 조합할 수 있습니다.

Docker Buildx Bake Override 실무 활용 예제

개발 환경 설정 변경

기본 설정:

docker-bake.hcl

target "app" {

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

  tags = [
    "company/app:latest"
  ]

}

개발 Override:

docker-bake.override.hcl

target "app" {

  tags = [
    "company/app:dev"
  ]

}

결과:

개발 환경에서는:

company/app:dev

운영 환경에서는:

company/app:latest

환경에 맞는 이미지를 관리할 수 있습니다.

Docker Buildx Bake Override와 CI/CD 활용

CI 환경에서는 별도의 설정을 적용할 수 있습니다.

예:

docker-bake.ci.hcl

target "app" {

  cache-from = [
    "type=gha"
  ]

  cache-to = [
    "type=gha"
  ]

}

실행:

docker buildx bake
-f docker-bake.hcl
-f docker-bake.ci.hcl

효과:

• CI Cache 적용
• 빌드 속도 향상
• 환경별 설정 분리

Docker Buildx Bake Override와 Production 배포

운영 환경에서는 보안과 안정성을 위한 설정을 추가할 수 있습니다.

예:

docker-bake.production.hcl

target "app" {

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

  push = true

}

운영 빌드:

docker buildx bake
-f docker-bake.hcl
-f docker-bake.production.hcl

운영 환경에 맞는 설정으로 빌드할 수 있습니다.

Linux 서버 문제 해결

하나의 Bake 파일로 개발과 운영 환경을 관리하고 있었습니다.

기존:

docker-bake.hcl

target "app" {

  tags = [
    "company/app:latest"
  ]

}

문제:

• 개발 테스트 때마다 파일 수정 필요
• 운영 설정과 충돌 발생
• 잘못된 Tag 배포 가능

Override 적용:

docker-bake.override.hcl

target "app" {

  tags = [
    "company/app:dev"
  ]

}

실행:

docker buildx bake

결과:

개발 환경에서는 dev Tag 사용

운영 설정은 기본 파일 유지

환경별 설정을 안전하게 분리할 수 있었습니다.

Docker Buildx Bake Override 사용 시 주의사항

첫 번째는 Override 파일 적용 순서를 확인해야 합니다.

두 번째는 동일한 Target 이름을 사용할 경우 기존 설정이 변경될 수 있습니다.

세 번째는 운영 환경 Override 파일은 별도 관리하는 것이 좋습니다.

네 번째는 민감한 정보는 Bake 파일에 직접 저장하지 않는 것이 좋습니다.

Best Practice

Docker Buildx Bake Override 활용 방법:

• 기본 설정과 환경 설정 분리
• 개발·스테이징·운영 파일 관리
• CI/CD 전용 Override 사용
• 공통 설정은 기본 파일 유지
• 환경별 Tag 관리
• 배포 전 Build 설정 확인

자주 묻는 질문

Docker Buildx Bake Override는 무엇인가요?

기존 Bake 설정을 환경에 맞게 변경하거나 추가하는 기능입니다.

Override 파일 이름은 무엇인가요?

기본적으로:

docker-bake.override.hcl

파일을 자동으로 사용합니다.

여러 Override 파일을 사용할 수 있나요?

가능합니다.

-f 옵션으로 여러 Bake 파일을 조합할 수 있습니다.

개발과 운영 설정을 분리할 수 있나요?

가능합니다.

환경별 Override 파일을 만들어 각각 관리할 수 있습니다.

마무리

Docker Buildx Bake Override는 하나의 Docker 프로젝트에서 다양한 환경을 효율적으로 관리하기 위한 중요한 기능입니다.

기본 Bake 설정은 유지하면서 개발, 테스트, 운영, CI/CD 환경에 필요한 설정만 변경할 수 있어 관리성과 안정성을 높일 수 있습니다.

특히 여러 Docker 이미지를 운영하거나 자동 배포 환경을 구성하는 경우 Override 기능을 활용하면 반복적인 설정 변경을 줄이고 더욱 체계적인 Docker 빌드 시스템을 구축할 수 있습니다.