Docker Image를 Build할 때 가장 기본이 되는 요소 중 하나는 Build Context입니다.

Docker Build는 단순히 Dockerfile만 사용하는 것이 아니라 Dockerfile이 접근할 수 있는 파일과 디렉터리 범위를 함께 전달합니다.

예:

project/

├── Dockerfile

├── package.json

├── src/

└── config/

Build 실행:

docker build .

여기서 . 부분이 바로 Build Context입니다.

Docker Buildx Bake에서도 Context를 Target별로 설정하여 다양한 Build 환경을 관리할 수 있습니다.

예:

docker-bake.hcl

target "app" {

  context = "."

  dockerfile = "Dockerfile"

}

실행:

docker buildx bake app

결과:

Build Context 전달

↓

Dockerfile 실행

↓

Image 생성

이번 글에서는 Docker Buildx Bake Context의 개념부터 Context 지정 방법, 여러 Context 관리, Git Context 활용, Build 최적화 방법까지 자세히 알아보겠습니다.

Table of Contents

Docker Buildx Bake Context란 무엇인가?

Docker Build Context는 Docker Build 과정에서 Docker Engine으로 전달되는 파일 범위입니다.

기본 구조:

Build Context

↓

Dockerfile

↓

COPY / ADD 명령 사용

↓

Image 생성

예:

Dockerfile:

FROM node:20

COPY package.json .

COPY src/ ./src/

RUN npm install

이때 Docker는 Context 안에 있는 파일만 사용할 수 있습니다.

Docker Buildx Bake Context가 필요한 이유

잘못된 Context 설정은 Build 속도와 관리 효율에 영향을 줍니다.

예:

project/

├── app/

├── logs/

├── backup/

└── node_modules/

전체 Context 사용:

docker build .

문제:

불필요한 파일 전달
Build 시간 증가
Cache 효율 감소

최적화:

app/

↓

필요한 파일만 전달

장점:

Build 속도 향상
Image 생성 효율 증가
Cache 활용 개선

Docker Buildx Bake Context 기본 설정

docker-bake.hcl:

target "app" {

  context = "."

  dockerfile = "Dockerfile"

}

의미:

context

↓

현재 폴더 전체 사용

실행:

docker buildx bake app

Docker Buildx Bake Context 다른 경로 지정하기

프로젝트 구조:

project/

├── frontend/

│   └── Dockerfile

└── backend/

    └── Dockerfile

Bake 설정:

target "frontend" {

  context = "./frontend"

  dockerfile = "Dockerfile"

}


target "backend" {

  context = "./backend"

  dockerfile = "Dockerfile"

}

실행:

docker buildx bake frontend backend

각각 다른 Context로 Build됩니다.

Docker Buildx Bake Context와 Dockerfile 위치 설정

Context와 Dockerfile은 별도로 지정할 수 있습니다.

예:

target "app" {

  context = "./source"

  dockerfile = "./docker/Dockerfile"

}

구조:

project/

├── source/

│   └── app.js

└── docker/

    └── Dockerfile

유연한 프로젝트 구조를 만들 수 있습니다.

Docker Buildx Bake Git Context 사용법

Docker Buildx Bake는 Git Repository를 Context로 사용할 수 있습니다.

예:

target "app" {

  context = "https://github.com/company/project.git"

}

동작:

Git Repository

↓

Clone

↓

Build Context 생성

↓

Image Build

활용:

Remote Build
CI/CD 환경
자동 배포

Docker Buildx Bake Context와 .dockerignore 활용

Context 최적화에서는 .dockerignore가 중요합니다.

예:

.dockerignore

node_modules

.git

logs

temp

효과:

불필요한 파일 제외

↓

Context 크기 감소

↓

Build 속도 향상

권장:

Git 폴더 제외
Log 파일 제외
Cache 파일 제외
테스트 결과 제외

Docker Buildx Bake Context 여러 개 관리하기

Microservice 환경에서는 여러 Context를 사용할 수 있습니다.

예:

target "api" {

  context = "./services/api"

}


target "worker" {

  context = "./services/worker"

}


target "frontend" {

  context = "./services/frontend"

}

구조:

services/

├── api

├── worker

└── frontend

각 서비스별 독립 Build가 가능합니다.

Docker Buildx Bake Context와 Build Args 활용

Context와 변수는 함께 사용할 수 있습니다.

예:

variable "SERVICE" {

  default = "api"

}


target "app" {

  context = "./services/${SERVICE}"

}

실행:

SERVICE=worker docker buildx bake app

결과:

./services/worker

↓

Build Context 사용

Docker Buildx Bake Context CI/CD 활용

CI/CD에서는 필요한 Context만 Build하는 것이 중요합니다.

예:

- name: Build Backend

  run: |

    docker buildx bake backend --push

구조:

Code 변경

↓

해당 서비스 Context 선택

↓

Image Build

↓

Registry Push

Monorepo 프로젝트에서 특히 유용합니다.

Docker Buildx Bake Context 실무 예제

프로젝트:

application/

├── services/

│   ├── api/

│   │   └── Dockerfile

│   │

│   └── worker/

│       └── Dockerfile

└── docker-bake.hcl

docker-bake.hcl:

target "api" {

  context = "./services/api"

  dockerfile = "Dockerfile"

  tags = [

    "registry.company.com/api:v1"

  ]

}


target "worker" {

  context = "./services/worker"

  dockerfile = "Dockerfile"

  tags = [

    "registry.company.com/worker:v1"

  ]

}

실행:

docker buildx bake api worker --push

결과:

API Image Build

↓

Worker Image Build

↓

Registry Push

Docker Buildx Bake Context 확인 방법

최종 설정 확인:

docker buildx bake --print app

확인:

Context 경로
Dockerfile 위치
Tag
Platform 설정

Build Context 크기 확인:

docker buildx du

Docker Buildx Bake Context 문제 해결

COPY 파일 오류 발생

오류:

failed to calculate checksum

원인:

Context 외부 파일 접근

해결:

필요한 파일을 Context 내부로 이동합니다.

Build 시간이 느린 경우

확인:

Context 크기
.dockerignore 설정
불필요한 파일

Git Context 오류

확인:

Repository 주소
접근 권한
Branch 정보

Docker Buildx Bake Context 사용 시 주의사항

첫 번째는 Context 크기를 최소화하는 것이 좋습니다.

두 번째는 Dockerfile에서 Context 외부 파일을 사용할 수 없습니다.

세 번째는 .dockerignore를 적극 활용해야 합니다.

네 번째는 Monorepo에서는 서비스별 Context 분리가 효과적입니다.

Best Practice

Docker Buildx Bake Context 활용 방법:

필요한 파일만 Context 지정
.dockerignore 활용
서비스별 Context 분리
Git Context 활용
CI/CD 최적화
Build 속도 개선

자주 묻는 질문

Docker Buildx Bake Context는 무엇인가요?

Docker Build 과정에서 전달되는 파일 범위입니다.

Context가 크면 어떤 문제가 있나요?

Build 시간이 증가하고 Cache 효율이 떨어질 수 있습니다.

여러 Context를 사용할 수 있나요?

가능합니다.

Target마다 다른 Context를 지정할 수 있습니다.

Git Repository도 Context로 사용할 수 있나요?