Multi-Architecture Images

docker buildx (Preferred)

This is the preferred way to build images, and can be completed on a single host with binfmt support correctly installed.

Reference:

platform_list="linux/amd64,linux/arm/v7"

if ! docker buildx inspect builder; then
    docker buildx create --name builder --driver docker-container --node default --platform "${platform_list}"
fi
docker buildx use builder

docker buildx build . --push --tag "${tag}" --platform "${platform_list}"

docker manifest

Multi-architecute images are created using the docker manifest command, which is currently experimental. See Enable Experimental Features.

Reference:

Create and Push the Manifest

# build or pull images
docker pull ${IMAGE_REPO}:${IMAGE_TAG}-${ARCH1}
docker pull ${IMAGE_REPO}:${IMAGE_TAG}-${ARCH2}

# create the manifest
docker manifest create ${IMAGE_REPO}:${IMAGE_TAG} \
  ${IMAGE_REPO}:${IMAGE_TAG}-${ARCH1} \
  ${IMAGE_REPO}:${IMAGE_TAG}-${ARCH2}

# annotate the manifest with os / architecture requirements
# NOTE: this should not be necessary
#docker manifest annotate ${IMAGE_REPO}:${IMAGE_TAG} \
#  ${IMAGE_REPO}:${IMAGE_TAG}-${ARCH1} \
#  --os linux --arch amd64
#docker manifest annotate ${IMAGE_REPO}:${IMAGE_TAG} \
#  ${IMAGE_REPO}:${IMAGE_TAG}-${ARCH2} \
#  --os linux --arch arm

# inspect the manifest to check it's correct
docker manifest inspect ${IMAGE_REPO}:${IMAGE_TAG}

# push the manifest as :${IMAGE_TAG}
docker manifest push ${IMAGE_REPO}:${IMAGE_TAG}

# also push as :latest...
mv ~/.docker/manifests/${IMAGE_REPO//\//_}-{${IMAGE_TAG},latest}
docker manifest push --purge ${IMAGE_REPO}:latest

Note

There is currently no way to tag this manifest and re-use it, for example pushing both a v1 and latest image. The whole process must be completed for each tag.

Tip

There is currently no way to remove a manifest via the CLI... but:

  • You can use docker manifest push --purge
  • The files are stored in ~/.docker/manifests/

Use the Image

docker run --rm -it ${IMAGE_REPO}:${IMAGE_TAG}