Best Practices for Building Multi-Architecture Images with a Unified Tag in Enterprise…

Best Practices for Building Multi-Architecture Images with a Unified Tag in Enterprise Infrastructure

Background

With the growing adoption of ARM-based CPUs in enterprise environments, it’s increasingly important to build software images that support both traditional AMD64 (x86_64) and ARM architectures. To streamline the CI/CD process and minimize pipeline modifications, the goal is to build multi-architecture images that can be deployed under a single tag.

This article outlines how to set up the necessary tools and two approaches for achieving this: using an emulator for cross-platform builds or creating architecture-specific images and combining them with a manifest.

Prerequisites

Before getting started, ensure the following are installed and functional on your machine:

1. Docker : The primary tool for building and managing container images.

2. Docker Buildx : A plugin that enables advanced build capabilities like cross-platform builds and caching optimization.

• Install Buildx on Linux :

mkdir -p ~/.docker/cli-plugins
# Download the appropriate buildx version for your architecture
curl -sLo ~/.docker/cli-plugins/docker-buildx ${download_link}

• Create a Buildx Builder :

docker buildx create --name buildx --use

1. (Optional) Kaniko : An alternative image-building tool for environments where Docker isn’t suitable.

Approach 1: Cross-Platform Builds Using Emulation

(Not recommended for production environments)

Steps:

1. Install QEMU Emulator : Install the emulator library to support architectures different from your host machine.

docker run --privileged --rm tonistiigi/binfmt --install all

2. Build Multi-Platform Images : Use the buildx command with platform-specific parameters.

docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 \
-t your_image_name:tag --push .

Limitations :

• Performance is often subpar, especially on Linux machines.

• On AMD64 hosts, builds can be up to 100x slower, and binary compatibility issues may arise on ARM machines.

• This method is better suited for local development rather than production.

Approach 2: Architecture-Specific Builds with a Unified Tag

(Recommended for production environments)

Process Overview:

This approach involves building architecture-specific images and combining them into a single multi-architecture image using Docker’s manifest functionality.

1. Build Architecture-Specific Images :

Build and tag images for each architecture.

docker buildx build -t your_image_name:tag-${{arch}} --push .

1. Create a Manifest, a special image tag :

Combine the architecture-specific images into a single tag.

docker manifest create your_image_name:tag \
your_image_name:tag-amd64 \
your_image_name:tag-arm64

1. Annotate the Manifest :

Add metadata for each architecture.

docker manifest annotate your_image_name:tag your_image_name:tag-amd64 --os linux --arch amd64
docker manifest annotate your_image_name:tag your_image_name:tag-arm64 --os linux --arch arm64

1. Push the Manifest to the Repository :

Sync the unified image to your repository.

docker manifest push your_image_name:tag

Conclusion

While QEMU-based emulation offers a way to build multi-platform images, its inefficiency and compatibility issues make it unsuitable for production. The recommended approach is to build images directly on their respective architectures and combine them using the manifest functionality. This ensures reliability, performance, and consistency across deployment environments. Now, it runs successfully in our production environment.

whole-build-images-pipeline