DEV Community

Brian,Kun Liu
Brian,Kun Liu

Posted on • Originally published at Medium on

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}
Enter fullscreen mode Exit fullscreen mode
  • Create a Buildx Builder :
docker buildx create --name buildx --use
Enter fullscreen mode Exit fullscreen mode
  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
Enter fullscreen mode Exit fullscreen mode

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 .
Enter fullscreen mode Exit fullscreen mode

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 .
Enter fullscreen mode Exit fullscreen mode
  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
Enter fullscreen mode Exit fullscreen mode
  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
Enter fullscreen mode Exit fullscreen mode
  1. Push the Manifest to the Repository :

Sync the unified image to your repository.

docker manifest push your_image_name:tag
Enter fullscreen mode Exit fullscreen mode

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

Image of Timescale

Timescale – the developer's data platform for modern apps, built on PostgreSQL

Timescale Cloud is PostgreSQL optimized for speed, scale, and performance. Over 3 million IoT, AI, crypto, and dev tool apps are powered by Timescale. Try it free today! No credit card required.

Try free

Top comments (0)

Dev Diairies image

User Feedback & The Pivot That Saved The Project

🔥 Check out Episode 3 of Dev Diairies, following a successful Hackathon project turned startup.

Watch full video 🎥

👋 Kindness is contagious

Explore this insightful write-up, celebrated by our thriving DEV Community. Developers everywhere are invited to contribute and elevate our shared expertise.

A simple "thank you" can brighten someone’s day—leave your appreciation in the comments!

On DEV, knowledge-sharing fuels our progress and strengthens our community ties. Found this useful? A quick thank you to the author makes all the difference.

Okay