How to tag an image as `latest` using Docker Buildx

I'm using Docker Buildx to build my images to multiple architectures, as I'm building them on a MacOS (arm64) but want them to run on a Cloud Run (amd64).

I'm running:

$ docker buildx build \
    --push \
    --platform linux/amd64,linux/arm64 \
    --tag stanleysathler/terraform-starter-carts-api:1.0.0 \
    --file carts-api/docker/Dockerfile \
    ./carts-api

It builds and publishes my images to Docker Hub. But then, I want to have a tag latest pointing to this latest image too. Tried:

$ docker tag \
  stanleysathler/terraform-starter-carts-api:1.0.0 \
  stanleysathler/terraform-starter-carts-api:latest

$ docker push \
  stanleysathler/terraform-starter-carts-api:latest

But I get this:

Error response from daemon: No such image: stanleysathler/terraform-starter-carts-api:1.0.0
The push refers to repository [docker.io/stanleysathler/terraform-starter-carts-api]
An image does not exist locally with the tag: stanleysathler/terraform-starter-carts-api

It feels like Buildx builds the image, publishes it, but don't create the local image.

How can I publish a latest tag pointing to my latest build using Docker Buildx?

Solution

You can pass --tag multiple times:

docker buildx build \
    --push \
    --platform linux/amd64,linux/arm64 \
    --tag stanleysathler/terraform-starter-carts-api:1.0.0 \
    --tag stanleysathler/terraform-starter-carts-api:latest \
    --file carts-api/docker/Dockerfile \
    ./carts-api

Otherwise, if you need to retag an image that is already pushed to a registry, there are multiple 3rd party tools that do this directly with registry API calls that avoids the need to pull any image layers. Those tools include crane from Google, oras from Microsoft, skopeo from RedHat, and regctl from myself. Each of these includes an image copy command, which when the repo name is the same, is effectively a retag.

I'd avoid outputting and tagging the image on the local docker engine since, unless you have enabled the currently experimental containerd management for images, the image is first dereferenced to a single platform image, losing the ability to run on both arm64 and amd64.