Buildah로 멀티플랫폼 이미지 빌드하기

Buildah를 사용해 여러 CPU 아키텍처용 이미지를 빌드하는 방법을 설명하는 문서예요. 멀티플랫폼 빌드는 서로 다른 하드웨어 플랫폼에서 동작하는 이미지를 만들고, Docker가 각 배포 대상에 적합한 이미지를 자동으로 선택해요.

아키텍처별 빌드 작업과 이를 하나의 매니페스트로 합치는 작업을 구성하는 예시를 옆에서 설명해 주는 방식으로 정리했어요.

출처: 문서

본문

Buildah를 사용해 여러 CPU 아키텍처용 이미지를 빌드하세요. 멀티플랫폼 빌드는 서로 다른 하드웨어 플랫폼에서 동작하는 이미지를 만들고, Docker는 각 배포 대상에 적합한 이미지를 자동으로 선택해요.

전제 조건

이미지를 빌드할 Dockerfile.
(선택 사항) 서로 다른 CPU 아키텍처에서 실행되는 GitLab 러너.

멀티플랫폼 이미지 빌드하기

Buildah로 멀티플랫폼 이미지를 빌드하려면:

대상 아키텍처별로 별도의 빌드 작업을 구성하세요.
아키텍처별 이미지를 결합하는 매니페스트 작업을 만드세요.
매니페스트 작업이 결합된 매니페스트를 레지스트리에 푸시하도록 구성하세요.

각 아키텍처에서 작업을 실행하면 CPU 명령어 변환으로 인한 성능 문제를 피할 수 있어요. 하지만 필요하다면 단일 아키텍처에서 두 빌드를 모두 실행할 수도 있어요. 비네이티브 아키텍처용 빌드는 빌드 시간이 더 느릴 수 있어요.

다음 예시는 두 개의 Linux의 GitLab 호스팅 러너를 사용해요.

saas-linux-small-arm64
saas-linux-small-amd64

stages:
  - build

variables:
  STORAGE_DRIVER: vfs
  BUILDAH_FORMAT: docker
  FQ_IMAGE_NAME: "$CI_REGISTRY_IMAGE:latest"

default:
  image: quay.io/buildah/stable
  before_script:
    - echo "$CI_REGISTRY_PASSWORD" | buildah login -u "$CI_REGISTRY_USER" --password-stdin $CI_REGISTRY

build-amd64:
  stage: build
  tags:
    - saas-linux-small-amd64
  script:
    - buildah build --platform=linux/amd64 -t $CI_REGISTRY_IMAGE:amd64 .
    - buildah push $CI_REGISTRY_IMAGE:amd64

build-arm64:
  stage: build
  tags:
    - saas-linux-small-arm64
  script:
    - buildah build --platform=linux/arm64/v8 -t $CI_REGISTRY_IMAGE:arm64 .
    - buildah push $CI_REGISTRY_IMAGE:arm64

create_manifest:
  stage: build
  needs: ["build-arm64", "build-amd64"]
  tags:
    - saas-linux-small-amd64
  script:
    - buildah manifest create $FQ_IMAGE_NAME
    - buildah manifest add $FQ_IMAGE_NAME docker://$CI_REGISTRY_IMAGE:amd64
    - buildah manifest add $FQ_IMAGE_NAME docker://$CI_REGISTRY_IMAGE:arm64
    - buildah manifest push --all $FQ_IMAGE_NAME

이 파이프라인은 amd64와 arm64로 태그된 아키텍처별 이미지를 만들고, 이를 latest 태그 아래의 단일 매니페스트로 결합해요.

문제 해결

인증 오류로 빌드 실패

레지스트리 인증 실패가 발생하면:

CI_REGISTRY_USER와 CI_REGISTRY_PASSWORD 변수가 사용 가능한지 확인하세요.
대상 레지스트리에 대한 푸시 권한이 있는지 확인하세요.
외부 레지스트리의 경우 프로젝트의 CI/CD 변수에 인증 자격 증명이 올바르게 구성되었는지 확인하세요.

멀티플랫폼 빌드 실패

멀티플랫폼 빌드 문제:

Dockerfile의 기본 이미지가 대상 아키텍처를 지원하는지 확인하세요.
모든 대상 플랫폼에 아키텍처별 의존성이 있는지 확인하세요.
아키텍처별 로직을 위해 Dockerfile에서 조건문 사용을 고려하세요.

오류: `Error during unshare(CLONE_NEWUSER): Operation not permitted`

Buildah 또는 Docker BuildKit을 rootless 모드로 사용해 CI/CD 작업에서 Docker 이미지를 빌드할 때 Error during unshare(CLONE_NEWUSER): Operation not permitted를 만날 수 있어요.

이 오류는 rootless 컨테이너 빌드에 필요한 보안 옵션이 설정되지 않았을 때 발생해요.

이 문제를 해결하려면 러너의 config.toml 파일에서 [runners.docker] 섹션을 구성하세요.

[runners.docker]
  security_opt = ["seccomp:unconfined", "apparmor:unconfined"]

자세한 내용은 BuildKit rootless Docker 빌드 및 보안 요구 사항을 참고하세요.

더 알아보기

rootless 컨테이너에서 Buildah를 사용하는 전체 튜토리얼은 OpenShift의 GitLab Runner Operator로 rootless 컨테이너에서 Buildah 사용하기 문서를 참고하세요. Docker 데몬 없이 이미지를 빌드하는 다른 방법은 Docker를 대체하는 방법 문서에서 볼 수 있답니다.

Buildah로 멀티플랫폼 이미지 빌드하기