Docker ARM·AMD64 배포: 멀티아키텍처 이미지와 네이티브 패키지 검증

AI Editter

개발용 Mac에서 만든 이미지가 서버에서 exec format error로 시작되지 않는다면 CPU 아키텍처를 확인합니다. 하지만 --platform 옵션을 추가해 빌드가 끝났다고 모든 네이티브 라이브러리와 앱 동작까지 검증된 것은 아닙니다.

멀티플랫폼 이미지는 하나의 태그 아래 플랫폼별 이미지를 연결합니다. 목표는 두 플랫폼에 맞는 파일이 들어 있고, 실제 대상에서 같은 기능을 제공하는지 확인하는 것입니다.

빌드 환경과 실행 환경을 구분

항목	기록
빌드 머신	CPU·OS·Buildx builder
목표 플랫폼	linux/amd64, linux/arm64 등
베이스 이미지	두 플랫폼 지원 여부
네이티브 의존성	C/C++ 확장·드라이버·바이너리
배포 대상	실제 서버·노드의 아키텍처

베이스 이미지가 멀티플랫폼이어도 나중에 다운로드한 실행 파일이 amd64 전용이면 실패할 수 있습니다. 압축 파일 이름과 설치 스크립트의 아키텍처 분기까지 확인합니다.

세 가지 빌드 방식의 차이

Docker는 에뮬레이션, 여러 네이티브 빌더, 크로스 컴파일 방식을 설명합니다. 멀티플랫폼 빌드 공식 문서를 기준으로 프로젝트에 맞는 방식을 선택합니다.

에뮬레이션은 시작하기 편하지만 컴파일 같은 작업이 느릴 수 있습니다. 네이티브 빌더는 플랫폼별 실행 환경을 관리해야 합니다. 크로스 컴파일은 언어와 의존성이 지원해야 하며 빌드 플랫폼과 목표 플랫폼을 구분해야 합니다.

QEMU에서 빌드·실행이 됐다는 사실은 실제 대상의 성능과 모든 하드웨어 의존 동작을 보증하지 않습니다. 최종 시험은 실제 목표 환경을 포함하는 것이 좋습니다.

Buildx로 두 플랫폼을 게시하는 예

다음은 승인된 시험 레지스트리에 올리는 명령 형식입니다. 주소와 태그를 자신의 비공개 시험 저장소로 바꾸고 게시 권한을 확인합니다.

docker buildx inspect --bootstrap
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t registry.example.com/team/app:release-test \
  --push .
docker buildx imagetools inspect registry.example.com/team/app:release-test

inspect 결과에 목표 플랫폼의 이미지가 실제로 포함됐는지 확인합니다. 태그 이름에 arm64를 붙였다는 사실은 해당 아키텍처 이미지라는 증거가 아닙니다.

배포 기록에는 태그뿐 아니라 이미지 digest와 소스 커밋을 남깁니다. 같은 태그를 나중에 덮어쓰면 어느 이미지를 시험했는지 모호해질 수 있습니다.

호스트의 패키지를 이미지에 복사하지 않기

호스트에서 설치한 node_modules, Python 가상환경, 컴파일된 바이너리를 다른 플랫폼 이미지에 그대로 COPY하면 문제가 생길 수 있습니다. 목표 플랫폼에 맞는 빌드 단계에서 의존성을 설치하거나 올바르게 크로스 컴파일합니다.

glibc와 musl, 운영체제 패키지 버전도 확인합니다. 같은 arm64라도 서로 다른 런타임 환경에서 동작이 달라질 수 있습니다. 작은 베이스 이미지로 바꾸는 작업은 아키텍처 전환과 분리해 시험하면 원인을 찾기 쉽습니다.

다운로드 URL을 구성할 때 Docker의 TARGETARCH 값과 공급업체의 파일 이름이 동일한지 확인합니다. arm64, aarch64, x86_64, amd64가 서로 다른 명명 규칙으로 쓰일 수 있습니다.

플랫폼별 시험표

시험	AMD64	ARM64
컨테이너 시작·종료	확인	확인
네이티브 모듈 import	확인	확인
핵심 API·파일 처리	동일 기대 결과	동일 기대 결과
DB·외부 연동	확인	확인
종료 신호 처리	확인	확인
대표 부하·메모리	별도 측정	별도 측정

성능 숫자는 실제 동일 조건에서 측정해야 합니다. 이 글은 특정 아키텍처가 몇 퍼센트 빠르다고 가정하지 않습니다. 처리량뿐 아니라 요청당 비용과 오류, 메모리 사용을 함께 봅니다.

일부 서버부터 전환하고 되돌릴 이미지를 남긴다

트래픽 일부 또는 비핵심 워커에서 시작해 결과를 관찰합니다. 아키텍처가 섞인 클러스터라면 스케줄링 조건과 이미지 선택이 맞는지 확인합니다. 플랫폼이 없는 이미지를 잘못 배치했을 때 어떤 오류로 드러나는지도 시험합니다.

롤백할 때는 이전 아키텍처용 이미지와 실행 노드 용량이 남아 있어야 합니다. 데이터 형식과 DB 변경이 함께 들어갔다면 이전 코드 호환성도 확인합니다.

최종적으로 빌드 성공, 매니페스트 포함, 실제 실행, 업무 결과, 성능을 각각 기록합니다. 이 다섯 단계가 있어야 플랫폼 옵션을 바꾼 작업을 운영 가능한 전환으로 만들 수 있습니다.