This page explains what multi-architecture (multi-arch) images are, why thearchitectures of nodes and container images are important, and why multi-archimages make deploying workloads to GKE clusters easier.This page also provides guidance about how you can check if yourworkloads are ready to run on Arm, and how you can build multi-arch images.

For a tutorial about deploying across architectures with multi-arch images, seeMigrate x86 application on GKE to multi-arch with Arm.

Amulti-arch image is an image that can support multiple architectures. It looks like a singleimage with a single tag, but it is a list of images targeting multiplearchitectures organized by a manifest list. Multi-arch images are compatiblewith theDocker Image Manifest V2 Scheme 2 orOCI Image Index Specifications.When you deploy a multi-arch image to a cluster, GKEautomatically chooses the right image that is compatible with the architectureof the node to which it is being deployed. Once you have a multi-arch image fora workload, you can seamlessly deploy this workload across multiplearchitectures.

Multi-arch images are most useful when you want to use the same workload acrossarchitectures. Alternatively, you can use container images with asingle architecture with any types of GKE nodes. If you are onlyusing a workload on one architecture and you already have a compatible image,you do not need to build a multi-arch image.

If you are using a single-arch image or multi-arch image that is Arm-compatibleand you want to deploy it to an Arm node, you must follow the instructions toinclude the necessary fields so that GKE schedules the workloadas expected. To learn more, seePrepare an Arm workload for deployment.You do not need to add these fields to schedule workloads if the workloads areonly going to be scheduled to x86-based nodes.

Why is the architecture of a GKE node important for workloads?

GKE nodesare individual Compute Engine VM instances which GKEcreates and manages on your behalf. Each node is of a standard machine type(for example,t2a-standard-1) which uses either x86 (Intel or AMD) or Armprocessors. To learn more see,CPU platforms.

You must use container images that are compatible with the architecture of the node where you intend to run the workloads.For example, if you want to run a container image with thearm64 architecture,you must a machine type that supports Arm workloads, such ast2a-standard-1from theTau T2A machine series.You can use nodes with multiple architecture types in one GKEcluster. If you want to use one workload across multiple architecture types, youmust keep all of the container images and deployment files for the architecture-specificimages organized. Multi-arch images make the process of deploying acrossarchitecture types simpler.

Build multi-arch image to deploy across x86 and Arm nodes

The following commands useDocker, butyou might be able to use other container tools to accomplish the same tasks.

Is my workload ready for Arm?

If you have an existing container image, you can check if this workload is readyto run on an Arm node. The following sections explain how to do this by usingdocker run to attempt to run the container with the Arm architecture.

Prepare Docker in your x86 environment to check a container image

If you are running Docker in an x86 environment, you must download additionalpackages to run anarm64 container image. These instructions useapt forpackage management, but you can use your environment's package manager todownload the required packages.

If you are running Docker in an Arm environment, you can skip this section.

The following commands download packages and registerQEMU as the binfmt interpreter for architectures that your machine does not support:

sudoapt-getinstallqemubinfmt-supportqemu-user-staticdockerrun--rm--privilegedmultiarch/qemu-user-static--reset-pyes

After setting your binfmt interpreters, you can run thearm64 image in your x86 environment.

Check the workload for Arm readiness

If you are running Docker in an Arm environment, or have prepared your x86environment for running Arm images, run the following command:

dockerrun--platformlinux/arm64IMAGE_NAME

ReplaceIMAGE_NAME with the name of the container image.

The following output indicates that your container image is ready to run on Armnodes with your GKE cluster:

Hello from Docker!This message shows that your installation appears to be working correctly.

If your workload is ready to run on Arm, you can proceed toPrepare an Arm workload for deployment.

The following output indicates that your image is not ready to run on Arm:

Unable to find image 'hello-world:latest' locallylatest: Pulling from library/hello-world93288797bd35: Pull completeDigest: sha256:507ecde44b8eb741278274653120c2bf793b174c06ff4eaa672b713b3263477bStatus: Downloaded newer image for hello-world:lateststandard_init_linux.go:219: exec user process caused: exec format error

This output indicates that this is anx86_64 oramd64 image and you mustbuild anarm64 image. Proceed to the next section,Build a multi-arch image,where you can use a non-Arm-compatible container image, a Dockerfile, and builda multi-arch image that can run across architecture types.

Build a multi-arch image

If you have a Dockerfile, you can use it to build an Arm-compatible andx86-compatible multi-arch image that you can deploy across nodes with differentarchitecture types.

You must downloadDocker Buildx to complete the following steps. You must also have an existing Dockerfile.

Prepare your environment if you have an x86 VM and Arm VM

The following commands assume that you have both an Arm build VM and an x86build VM in your build environment, and your x86 VM can SSH as root into yourArm VM. If you only have an x86 VM in your build environment, follow theinstructions in the next section,Prepare your environment if you only have an x86 VM.

Prepare your environment to build multi-arch images:

1. Create a context for the x86 node using the local socket, and a context forthe Arm node using SSH:

   dockercontextcreateamd_node--docker"host=unix:///var/run/docker.sock"dockercontextcreatearm_node--docker"host=ssh://root@NODE_IP"

   ReplaceNODE_IP with the IP address of the Arm node.

2. Create a builder using the x86 node:

   dockerbuildxcreate--use--nameBUILDER_NAME--platformlinux/amd64amd_nodedockerbuildxcreate--append--nameBUILDER_NAME--platformlinux/arm64arm_node

   ReplaceBUILDER_NAME with a name that you choose forthe Buildx builder.

Prepare your environment if you only have an x86 VM

If you only have an x86 VM in your build environment, you can follow these stepsto prepare your environment to build multi-arch images. With this option, thebuild step might take longer.

1. InstallQEMU packages:

   dockerrun--rm--privilegedmultiarch/qemu-user-static

2. Create a multi-arch builder (the default builder does not support multi-arch):

   dockerbuildxcreate--nameBUILDER_NAME--use

   ReplaceBUILDER_NAME with a name that you choose forthe Buildx builder.

Build the image

Now that your environment is ready, run the following command to build amulti-arch image:

dockerbuildxbuild.-tPATH_TO_REGISTRY--platformlinux/amd64,linux/arm64--push

ReplacePATH_TO_REGISTRY with the path to your registry,ending with the name of your container image and a tag (for example,gcr.io/myproject/myimage:latest).

If you get an error message at this step, refer to theDocker guide and associated documentation to troubleshoot further.

Once you have built a multi-arch image, your workload is ready to run onArm. Proceed toPrepare an Arm workload for deployment.

What's next

• Prepare an Arm workload for deployment
• Migrate x86 application on GKE to multi-arch with Arm