How to build multi-architecture container images

As the demand for containerization continues to grow, developers face the challenge of deploying applications across various architectures and platforms. The Docker containerization platform provides a solution with its support for multi-architecture container images. In this article, we will explore the process of building Docker multi-architecture container images and the benefits it offers.

Understanding multi-architecture containers

Traditionally, Docker images were built and optimized for a specific architecture, such as x86 or ARM. However, with the advent of diverse hardware architectures and the rise of cloud platforms, the need for multi-architecture support became crucial. Multi-architecture containers enable deploying the same image across different architectures seamlessly.

Docker manifests

To achieve multi-architecture support, Docker introduced the concept of manifests. A manifest is a JSON file that describes a set of images for different platforms, collectively known as a manifest list. It provides a way to associate multiple image layers with a single reference. Docker automatically selects the appropriate image for the target platform during the container deployment.

Building multi-architecture images

To build multi-architecture container images, we need to follow these steps:

1. Create Dockerfiles: Start by creating separate Dockerfiles for each architecture you want to support. These Dockerfiles will define the instructions for building the container images.
2. Build images: Use Docker's build command to build the images for each architecture. Specify the appropriate Dockerfile for each build, along with the target architecture. For example, you can use the --platform flag to specify the architecture explicitly.
3. Tag images: Once the images are built, tag them with the appropriate platform-specific tags. These tags typically include the architecture name, such as AMD64, arm64, or ppc64le.
4. Push images: Push the tagged images to a Docker registry or any other container registry of your choice. Make sure the registry supports multi-architecture manifest lists.
5. Create manifest list: Finally, create a manifest list that references the different platform-specific images. The manifest list acts as a single entry point for pulling and deploying the multi-architecture container. Use the podman manifest create command to create the manifest list.
6. Push manifest list: Push the manifest list to the registry, linking it to the appropriate images for each architecture. This ensures that Docker pulls the correct image based on the target platform.

Testing multi-architecture containers

It is crucial to test multi-architecture containers thoroughly to ensure compatibility across different platforms. Set up a testing environment that includes hardware or virtual machines representing the target architectures. Pull the container images from the registry and deploy them on each platform to verify functionality and performance.

Benefits of multi-architecture containers

Deploying multi-architecture containers offers several benefits:

• Portability: Applications packaged as multi-architecture containers can run seamlessly on different hardware architectures, making it easier to migrate between platforms or cloud providers.
• Scalability: With multi-architecture support, scaling applications becomes more flexible, as you can leverage a diverse range of hardware architectures.
• Development efficiency: You can build, test, and distribute applications across various architectures simultaneously, reducing the time and effort required for cross-platform deployment.
• Future-proofing: Multi-architecture containers future-proof your applications, ensuring they can run on new architectures as they emerge.

Podman

To build Linux AMD64 and Linux ARM64 container images using Podman, you can use the following command:

# First, initialise the manifest
podman manifest create <image name>

# Build the image attaching them to the manifest
podman build --platform linux/amd64,linux/arm64  --manifest <image name>  .

# Finally publish the manifest
podman manifest push <image name>

In this example:

• We use the podman build command to initiate the build process.

• The --platform flag is used to specify the target platforms as linux/amd64,linux/arm64.

• The <image name> flag sets the tag for the container image. In this example, we use myregistry/myapp:latest .. Replace it with your desired image name and tag.

• The . at the end specifies the build context, indicating that the Dockerfile and associated files are located in the current directory.

By executing this command, Podman will build the container image for both Linux AMD64 and Linux ARM64 architectures. Podman leverages the host's architecture to handle the build process for the specified platforms.

Ensure that you have Podman properly installed and configured on your system before running the command. Additionally, make sure you have the necessary Dockerfile and any required files in the build context directory.

After running the command, Podman will execute the build process, creating separate container images for each platform specified. The resulting images will be tagged with the specified tag (myregistry/myapp:latest in this example), ready for further use or distribution.

Docker Buildx

To build Linux AMD64 and Linux ARM64 container images using Docker Buildx, you can use the following command:

docker buildx create --use --name mybuilder

docker buildx inspect --bootstrap

docker buildx build --platform linux/amd64,linux/arm64 --output "type=image,push=true" \
--tag myregistry/myapp:latest  --builder mybuilder .

docker buildx stop mybuilder

 

To set up Docker Buildx on your machine, follow these steps:

1. Install Docker: If you don't have Docker installed, download and install Docker for your operating system. You can find the installation instructions for various platforms on the official Docker website.

2. Enable experimental features: Docker Buildx is an experimental feature as of this writing, so you need to enable it in Docker. Open the Docker settings/preferences, go to the Experimental Features section, and toggle on the Enable Docker Buildx option.

3. Verify Docker Buildx installation: Open a terminal or command prompt and run the following command to verify if Docker Buildx is installed correctly:

        docker buildx version

4. To create a new builder instance for Docker Buildx, run the following command:

       docker buildx create --use

5. To verify that the builder instance is set up and ready to use, run:

   docker buildx inspect --bootstrap

   docker buildx create --use --name mybuilder
   
   docker buildx inspect --bootstrap
   
   docker buildx build --platform linux/amd64,linux/arm64 --output "type=image,push=true" \
   --tag myregistry/myapp:latest  --builder mybuilder .
   
   docker buildx stop mybuilder

In this example:

1. First, we create a new builder instance named mybuilder using docker buildx create --use --name mybuilder. This step sets up the Docker Buildx builder.

2. Next, we inspect the builder and ensure it is properly bootstrapped with docker buildx inspect --bootstrap.

3. Then, we use docker buildx build to initiate the build process. We specify the target platforms using the --platform flag as linux/amd64,linux/arm64 ..

4. We use --output "type=image,push=true" to specify that we want to output the built image as a Docker image and push it to the registry.

5. The --tag flag sets the tag for the Docker image, in this example, myregistry/myapp:latest.

6. We specify the builder to use with --builder mybuilder.

7. Finally, we specify the build context as . (current directory) and execute the build.

8. Once the build is complete, we stop the builder instance using docker buildx stop mybuilder.

By executing this command, Docker Buildx will utilize Podman as the underlying runtime to build the container images for both Linux AMD64 and Linux ARM64 architectures. It will automatically handle the cross-building process and create the appropriate images for each architecture specified in the --platform flag.

Make sure to replace myregistry/myapp:latest with your desired image name and tag, and adapt the command to match your specific registry and build context requirements.

Note: Ensure that you have Docker Buildx and Podman properly installed and configured on your system before running the command.

Conclusion

Building Docker multi-architecture container images opens up new possibilities for deploying applications across diverse platforms and hardware architectures. By leveraging Docker manifests and following the outlined steps, you can create and distribute container images that seamlessly run on different platforms, enhancing portability, scalability, and development.

Last updated: January 9, 2024