Container Registry:Build multi-architecture container images

How it works

A multi-arch image stores a manifest list alongside the individual image manifests. Each entry in the manifest list points to an image built for a specific architecture. When Docker or containerd pulls the image by tag, it reads the manifest list and fetches only the manifest that matches the host's architecture.

This means the same docker pull command works correctly on both an amd64 server and an Arm-based machine.

Prerequisites

Before you begin, make sure you have:

• A Container Registry Enterprise Edition instance. See Create a Container Registry Enterprise Edition instance

• The instance bound to a source code hosting platform. See Bind a source code hosting platform

• A project that compiles successfully on each target architecture

Supported architectures

Windows images are not currently supported. All supported architectures run on Linux.

If you select a single architecture, the image is built for that architecture and pushed with the specified tag. If you select multiple architectures, a separate image is built for each architecture and pushed to the same repository under the same tag.

Step 1: Create a project

Create a source code project from which the image will be built. The following Go source file and Dockerfile produce a binary that prints the architecture of the machine it runs on — useful for verifying that the correct image variant is pulled.

// Save as hello.go
package main

import (
    "fmt"
    "runtime"
)

func main() {
    fmt.Printf("Hello, %s!\n", runtime.GOARCH)
}

FROM golang:alpine AS builder
RUN mkdir /app
ADD . /app/
WORKDIR /app
RUN go build -o hello hello.go
FROM alpine
RUN mkdir /app
WORKDIR /app
COPY --from=builder /app/hello .
CMD ["./hello"]

The Dockerfile uses a multi-stage build: the golang:alpine stage compiles the binary, and the final alpine stage produces a minimal image.

Step 2: Create an image repository

Create an image repository and bind it to the source code project. All image builds triggered from the project are pushed to this repository.

1. Log on to the Container Registry console.

2. Log on to the Container Registry console.

3. In the top navigation bar, select a region.

4. In the left-side navigation pane, click Instances.

5. On the Instances page, click the Enterprise Edition instance you want to manage.

6. In the left-side navigation pane, choose Repository > Repositories.

7. On the Repositories page, click Create Repository.

8. In the Repository Info step, configure Namespace, Repository Name, Repository Type, Tags, Accelerated Images, Summary, and Description. Then click Next.

9. In the Code Source step, configure the following parameters, then click Create Repository. Build Settings options:

   Parameter	Description
   Code Source	The source code hosting platform to bind to the repository.
   Build Settings	Options that control how images are built. See the table below.
   Build Rules	Rules that define when and how images are built.

   Option	Description
   Automatically Build Images When Code Changes	Triggers a build whenever code is pushed to a configured branch.
   Build With Servers Deployed Outside Chinese Mainland	Builds images on servers outside the Chinese mainland, then pushes them to the specified region. Enable this if your Dockerfile pulls base images from sources outside the Chinese mainland and the cross-border connection is unstable.
   Build Without Cache	Pulls the base image fresh on every build. Enabling this option may slow down builds.

After the repository is created, click it on the Repositories page. If Build appears in the left-side navigation pane of the repository management page, the repository is successfully bound to the source code repository.

Step 3: Add a build rule and select architectures

This step configures the build rule that tells Container Registry which branches to build from, how to tag the output images, and which architectures to target. In this example, the build rule targets linux/amd64 and linux/arm64.

1. Log on to the Container Registry console.

2. Log on to the Container Registry console.

3. In the top navigation bar, select a region.

4. In the left-side navigation pane, click Instances.

5. On the Instances page, click the Enterprise Edition instance you want to manage.

6. In the left-side navigation pane, choose Repository > Repositories.

7. On the Repositories page, find the image repository, then click Manage in the Actions column.

8. In the left-side navigation pane, click Build. In the Build Rules section, click Add Build Rule.

9. In the Build Information step, configure the following parameters, then click Next.

   Parameter	Description
   Type	The type of source code reference to watch. Valid values: Branch and Tag.
   Branch/Tag	The branch or tag to build from. Regular expressions are supported. For example, specifying release-(?<imageTag>\w*) automatically builds an image when code is pushed to a branch like release-v1, using v1 as the image tag. See Use regular expressions in named capturing groups. Note After specifying a regular expression, images can only be built by the system — manual builds are disabled.
   Dockerfile Directory	The subdirectory within the branch or tag that contains the Dockerfile. For example, if the Dockerfile is at the root of the master branch, enter master/Dockerfile.
   Dockerfile Filename	The name of the Dockerfile. Defaults to Dockerfile.

10. In the Tag step, configure the following parameters, click Save, then click Next.

    Click Add Configuration to add image tags. Up to three image tags are supported.

    Parameter	Description
    Image Tag	The tag for the built image, such as latest. If you used a named capturing group in the Branch/Tag field, you can reference the captured value here.
    Build Time	(Optional) Appends the push timestamp (UTC+8) to the tag, such as 20201015 or 202010151613. If set, only the system can trigger builds.
    Commit ID	(Optional) Appends characters from the most recent commit ID to the tag. By default, the first six characters are used. If set, only the system can trigger builds.

11. In the Build Configurations step, configure the following parameters, then click Confirm.

    Parameter	Description
    Build Architecture	The architectures to build images for. Select multiple architectures to build a separate image for each. All images are pushed under the same tag, forming a multi-arch image.
    Build Parameters	Runtime build arguments passed to the Dockerfile. Each argument is a case-sensitive key-value pair. Up to 20 build parameters are supported. Use build parameters to modify Dockerfile environment variables without changing the Dockerfile itself.

12. Trigger the build rule using one of the following methods: In the left-side navigation pane, click Image Tag to confirm the image was created.

    • In the Build Rules section of the Build page, find the build rule and click Build in the Actions column.

    • Push a commit to the master branch of the source code repository to trigger the rule automatically.

    To cancel a running build, go to the Build Log section of the Build page, find the build task, and click Cancel in the Actions column. To view build logs, click Log in the Actions column for the relevant build task.

Step 4: Verify the results

1. In the left-side navigation pane of the image repository management page, click Tags. Two images are listed under the main tag: one for Linux/AMD64 and one for Linux/ARM64.

   

2. Verify that the correct image variant is pulled on each architecture. On a Linux/AMD64 machine:

   docker run --rm xxx-registry.cn-hangzhou.cr.aliyuncs.com/test/golang-test:main

   Expected output:

   Hello, amd64!

   On a Linux/ARM64 machine:

   docker run --rm xxx-registry.cn-hangzhou.cr.aliyuncs.com/test/golang-test:main

   Expected output:

   Hello, arm!

Both machines use the same image tag. Each pulls the variant that matches its own architecture.

Appendix: Use regular expressions in named capturing groups

A named capturing group extracts part of a matched string and stores it under a named key, which you can then reference in templates.

The format for a named capturing group is:

(?<name>Expression)

For example, the following expression matches release-11-2-10 and captures each version component separately:

release-(?<major>\d*)-(?<minor>\d*)-(?<version>\d*)

The matched content is stored in groups named major, minor, and version. Use the following template to reassemble them as 11.2.10:

${major}.${minor}.${version}

What's next

To build and push a multi-arch image from a local machine instead of using the console, see Build and push a multi-arch image on an on-premises device to a Container Registry Enterprise Edition instance.