Build and push a multi-arch container image on an on-premises device to an image repository - Container Registry

Maintaining separate images with different tags for x86 and Arm architectures increases maintenance overhead. Use docker buildx to build multi-arch images from a Dockerfile, or use docker manifest to combine existing single-arch images under a single tag.

Prerequisites

Before you begin, make sure you have:

A Container Registry Enterprise Edition instance. For more information, see Create a Container Registry Enterprise Edition instance.
A Docker client installed on your on-premises device. For more information, see Install Docker.
Access to the Container Registry Enterprise Edition instance from the Docker client. Run the following command, replacing the placeholder with your registry address:
```
docker login --username=<your-username> <registry-address>
```
Example: docker login --username=xxx acr-test-registry.cn-hangzhou.cr.aliyuncs.com

Build a multi-arch image from a Dockerfile

Create a Dockerfile in your project directory. This example uses a Java Maven project:

# First stage: build environment
FROM maven:3.5.0-jdk-8-alpine AS builder

ADD ./pom.xml pom.xml
ADD ./src src/

RUN mvn clean package

# Second stage: minimal runtime environment
FROM openjdk:8-jre-alpine

COPY --from=builder target/my-app-1.0-SNAPSHOT.jar my-app-1.0-SNAPSHOT.jar

EXPOSE 8080

CMD ["java", "-jar", "my-app-1.0-SNAPSHOT.jar"]

Open a terminal in the project directory and run the following commands:
1. Disable the Provenance attestations option of docker buildx:
```
export BUILDX_NO_DEFAULT_ATTESTATIONS=1
```
2. Build the multi-arch image and push it to your image repository:
```
docker buildx build . -t acr-test-registry.cn-hangzhou.cr.aliyuncs.com/test/test:multi  --platform linux/amd64,linux/arm64 --push
```
  This command builds images for the amd64 and arm64 architectures and pushes them to the repository under a single multi-arch tag.
Note
Before you run the docker push command to push images to an image repository, you must run the docker login command to log on to the image repository. Example of a docker login command: docker login --username=xxx acr-test-registry.cn-hangzhou.cr.aliyuncs.com.

Create a multi-arch image from existing single-arch images

Use this method when you already have separate single-arch images and want to combine them under one multi-arch tag.

Run the docker tag command to re-tag the single-arch images, and push them to the Container Registry Enterprise Edition instance. This example uses an arm64 NGINX image and an amd64 NGINX image:

docker tag nginx:arm64 acr-test-registry.cn-hangzhou.cr.aliyuncs.com/multi-arch/nginx:arm64
docker push acr-test-registry.cn-hangzhou.cr.aliyuncs.com/multi-arch/nginx:arm64

docker tag nginx:amd64 acr-test-registry.cn-hangzhou.cr.aliyuncs.com/multi-arch/nginx:amd64
docker push acr-test-registry.cn-hangzhou.cr.aliyuncs.com/multi-arch/nginx:amd64

Run the docker manifest create command to create a manifest list and merge the images in step 1 into a multi-arch image:

docker manifest create acr-test-registry.cn-hangzhou.cr.aliyuncs.com/multi-arch/nginx:multi \
 acr-test-registry.cn-hangzhou.cr.aliyuncs.com/multi-arch/nginx:arm64 \
 acr-test-registry.cn-hangzhou.cr.aliyuncs.com/multi-arch/nginx:amd64

Run the docker manifest push command to push the manifest list to the Container Registry Enterprise Edition instance:
```
docker manifest push acr-test-registry.cn-hangzhou.cr.aliyuncs.com/multi-arch/nginx:multi
```
(Optional) Verify that the multi-arch image was pushed successfully:
```
docker manifest inspect acr-test-registry.cn-hangzhou.cr.aliyuncs.com/multi-arch/nginx:multi
```
The output lists the manifests for each included architecture.

References

To configure and run multi-arch image builds in the Container Registry console, see Build container images for multiple architectures.