Docker 이미지를 빌드할 때 기본적으로 BuildKit은 보안을 위해 제한된 환경에서 동작합니다.

하지만 실제 프로젝트에서는 빌드 과정에서 추가 권한이 필요한 경우가 있습니다.

예:

• 호스트 네트워크 사용
• 보안이 필요한 파일 접근
• 특정 시스템 기능 사용
• 외부 리소스 연결
• Docker Build 과정에서 추가 권한 필요

일반적인 Docker Build 환경에서는 이러한 작업이 제한됩니다.

예:

RUN curl https://example.com

외부 네트워크 접근이 필요한 경우 제한이 발생할 수 있습니다.

Docker Buildx Bake에서는 이러한 문제를 해결하기 위해 Entitlements 기능을 제공합니다.

예:

docker-bake.hcl

target "app" {

  entitlements = [
    "network.host"
  ]

}

빌드 과정에서 필요한 권한을 명시적으로 허용할 수 있습니다.

이번 글에서는 Docker Buildx Bake Entitlements의 개념부터 기본 사용법, network.host 설정, security.insecure 활용, 보안 주의사항까지 자세히 알아보겠습니다.

Docker Buildx Bake Entitlements란 무엇인가?

Docker Buildx Bake Entitlements는 BuildKit 빌드 과정에서 추가 권한을 허용하는 기능입니다.

기본 구조:

권한 요청

↓

Entitlement 허용

↓

Build 실행

예:

일반 Build

↓

제한된 환경


Entitlement 적용

↓

추가 기능 사용 가능

보안과 기능 사이의 균형을 관리하는 기능입니다.

Docker Buildx Bake Entitlements가 필요한 이유

기본 BuildKit 환경에서는 다음 기능들이 제한됩니다.

예:

• Host Network 접근
• Host File System 접근
• 일부 보안 기능 비활성화

문제:

Build 과정 실패

↓

필요 권한 부족

↓

추가 설정 필요

Entitlements 사용:

필요한 권한만 선택적 허용

↓

정상적인 Build 진행

Docker Buildx Bake Entitlements 종류

Docker Buildx에서 대표적으로 사용하는 Entitlement는 두 가지입니다.

network.host

Host Network 사용 권한입니다.

사용:

entitlements = [
  "network.host"
]

활용:

• 내부 네트워크 접근
• 특정 서버 연결
• 테스트 환경 구성

security.insecure

보안 제한을 해제하는 권한입니다.

사용:

entitlements = [
  "security.insecure"
]

활용:

• 특별한 Build 환경
• 낮은 수준의 시스템 접근 필요

Docker Buildx Bake network.host 사용법

docker-bake.hcl:

target "app" {

  entitlements = [
    "network.host"
  ]

}

실행:

docker buildx bake app

Build 과정에서 Host Network를 사용할 수 있습니다.

Dockerfile에서 Network 사용 예제

Dockerfile:

FROM ubuntu

RUN apt update && apt install -y curl

일반 Build에서는 네트워크 환경에 따라 실패할 수 있습니다.

Entitlement 적용:

docker-bake.hcl

target "app" {

  entitlements = [
    "network.host"
  ]

}

외부 리소스 접근이 필요한 Build 작업을 수행할 수 있습니다.

Docker Buildx Bake security.insecure 사용법

일부 Build 작업은 추가 시스템 권한이 필요할 수 있습니다.

예:

target "app" {

  entitlements = [
    "security.insecure"
  ]

}

활용:

• 특수 Build 환경
• 시스템 수준 테스트
• 특정 도구 실행

하지만 보안 위험이 증가하기 때문에 필요한 경우에만 사용하는 것이 좋습니다.

Docker Buildx Bake Entitlements 실행 옵션

명령어에서도 지정할 수 있습니다.

예:

docker buildx bake \
--allow network.host

또는:

docker buildx bake \
--allow security.insecure

필요한 권한만 명시적으로 허용합니다.

Docker Buildx Bake Entitlements와 Docker Build 비교

일반 Docker Build

특징:

• 기본 권한 제한
• 안전한 기본 환경
• 추가 접근 제한

Buildx Bake Entitlements 사용

특징:

• 필요한 권한 추가
• Build 기능 확장
• 세밀한 권한 관리

정리:

일반 Build

= 보안 중심

Entitlement Build

= 기능 확장

Docker Buildx Bake Entitlements 실무 활용 예제

내부 서버 접근 Build

상황:

회사 내부 Package Server에서 파일 다운로드 필요

기본:

RUN curl http://internal-server/package

문제:

네트워크 접근 제한

해결:

docker-bake.hcl

target "app" {

  entitlements = [
    "network.host"
  ]

}

결과:

내부 서버 접근 가능

CI/CD에서 Docker Buildx Bake Entitlements 활용

CI 환경에서는 필요한 권한만 추가합니다.

예:

- name: Build Image
  run: |
    docker buildx bake \
    --allow network.host

활용:

• 내부 Registry 접근
• 테스트 환경 연결
• 자동 Build

Docker Buildx Bake Entitlements와 보안 관리

Entitlements는 강력한 기능인 만큼 주의가 필요합니다.

위험:

권한 확대

↓

호스트 접근 증가

↓

보안 위험 증가

권장:

• 필요한 권한만 허용
• 운영 환경 검토 후 사용
• CI Secret과 함께 관리
• Build 로그 확인

Linux 서버 문제 해결

Docker 이미지를 빌드하면서 내부 서버에서 Package를 받아와야 했습니다.

기존:

docker buildx bake

문제:

Network 접근 실패

↓

Package 다운로드 실패

Entitlement 적용:

docker-bake.hcl

target "app" {

  entitlements = [
    "network.host"
  ]

}

결과:

• 내부 네트워크 접근 가능
• Build 정상 완료
• 필요한 권한만 적용

Docker Buildx Bake Entitlements 사용 시 주의사항

첫 번째는 모든 Build에 무조건 적용하지 않는 것이 좋습니다.

두 번째는 security.insecure 사용 시 보안 검토가 필요합니다.

세 번째는 운영 환경에서는 최소 권한 원칙을 적용해야 합니다.

네 번째는 CI/CD 환경에서도 허용 권한을 제한해야 합니다.

Best Practice

Docker Buildx Bake Entitlements 활용 방법:

• 필요한 권한만 추가
• network.host 최소 사용
• security.insecure 신중 사용
• CI 환경 권한 관리
• Build 환경별 설정 분리
• 보안 정책 적용

자주 묻는 질문

Docker Buildx Bake Entitlements는 무엇인가요?

Docker Build 과정에서 추가 권한을 허용하는 기능입니다.

왜 기본적으로 제한되어 있나요?

BuildKit은 보안을 위해 기본 권한을 제한합니다.

network.host는 언제 사용하나요?

Build 과정에서 Host Network 접근이 필요할 때 사용합니다.

security.insecure를 사용해도 되나요?

가능하지만 보안 위험이 증가하므로 필요한 상황에서만 사용하는 것이 좋습니다.

마무리

Docker Buildx Bake Entitlements는 제한된 BuildKit 환경에서 필요한 기능을 안전하게 확장하는 기능입니다.

네트워크 접근이나 특별한 시스템 권한이 필요한 프로젝트에서는 유용하게 사용할 수 있으며, 필요한 권한만 선택적으로 허용하는 것이 중요합니다.

특히 운영 환경과 CI/CD 환경에서는 최소 권한 원칙을 적용하여 보안성과 편의성을 함께 관리해야 합니다.

Docker Buildx Bake Entitlements를 올바르게 활용하면 더욱 유연하고 안정적인 Docker 빌드 환경을 구축할 수 있습니다.