How to use docker manifest push command to push a manifest list

Introduction

In this lab, you will learn how to effectively use the docker manifest push command to manage multi-architecture images. We will begin by creating a manifest list, which allows a single image name to refer to images built for different architectures and operating systems.

Following the creation of the manifest list, you will practice pushing it to a standard registry and also explore how to push to an insecure registry. Finally, you will learn how to push and then purge the local manifest list, ensuring efficient management of your Docker images.

Skills Graph

Create a manifest list

In this step, we will learn how to create a manifest list using the docker manifest create command. A manifest list is a list of image manifests, allowing you to use a single name to refer to images for different architectures and operating systems. This is particularly useful for building multi-architecture images.

First, let's pull two different images that we will use to create our manifest list. We will use the alpine image for amd64 and arm64 architectures.

docker pull alpine:latest
docker pull arm64v8/alpine:latest

You should see output indicating that the images are being pulled.

latest: Pulling from library/alpine
...
Status: Downloaded newer image for alpine:latest
latest: Pulling from arm64v8/alpine
...
Status: Downloaded newer image for arm64v8/alpine:latest

Now, we will create a manifest list named my-alpine:latest that includes the two images we just pulled. The syntax is docker manifest create MANIFEST_LIST IMAGE [IMAGE...].

docker manifest create my-alpine:latest alpine:latest arm64v8/alpine:latest

If the command is successful, you will not see any output. This command creates a local manifest list. To see the manifest list information, you can use the docker manifest inspect command.

docker manifest inspect my-alpine:latest

You should see output similar to this, showing the details of the manifest list, including the manifests for the amd64 and arm64 architectures.

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
  "manifests": [
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "size": 528,
      "digest": "sha256:...",
      "platform": {
        "architecture": "amd64",
        "os": "linux"
      }
    },
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "size": 528,
      "digest": "sha256:...",
      "platform": {
        "architecture": "arm64",
        "os": "linux"
      }
    }
  ]
}

This confirms that the manifest list my-alpine:latest has been successfully created and includes the specified images.

Push the manifest list to a registry

In this step, we will push the manifest list we created in the previous step to a Docker registry. By default, docker push pushes individual images. To push a manifest list, you need to use the docker manifest push command.

Before pushing, we need a registry to push to. For this lab, we will use Docker Hub. If you don't have a Docker Hub account, you can create one for free. You will need to log in to Docker Hub from your terminal.

docker login

You will be prompted to enter your Docker Hub username and password. Enter your credentials to log in.

Login with your Docker ID to push and pull images, scan them for vulnerabilities, sign and attest to them, and more.
Username: your_docker_username
Password: your_docker_password
Login Succeeded

Now that you are logged in, you can push the manifest list. The format for pushing to Docker Hub is your_docker_username/manifest_list_name:tag. Let's assume your Docker Hub username is your_docker_username. Replace your_docker_username with your actual Docker Hub username.

docker manifest push your_docker_username/my-alpine:latest

You should see output indicating that the manifest list and the associated images are being pushed to the registry.

Pushed manifest list your_docker_username/my-alpine:latest

After the push is complete, you can verify that the manifest list exists in your Docker Hub repository by visiting the Docker Hub website or by pulling the image on a different architecture.

Push the manifest list to an insecure registry

In this step, we will explore how to push a manifest list to an insecure registry. An insecure registry is a registry that does not use TLS/SSL certificates, which is not recommended for production environments but can be useful for testing or internal networks.

By default, Docker requires secure connections to registries. To push to an insecure registry, you need to configure the Docker daemon to allow insecure connections to that specific registry address.

For this lab, we will simulate an insecure registry by using a local registry running without TLS. First, let's run a local registry container. We will map port 5000 on the host to port 5000 on the container.

docker run -d -p 5000:5000 --name registry registry:2

You should see output similar to this, indicating the container is running:

Unable to find image 'registry:2' locally
2: Pulling from library/registry
...
Status: Downloaded newer image for registry:2
a1b2c3d4e5f6...

Now, we need to configure the Docker daemon to trust this insecure registry at localhost:5000. This requires modifying the Docker daemon configuration file. The location of this file can vary, but on most Linux systems, it's /etc/docker/daemon.json.

We will use sudo nano to edit this file.

sudo nano /etc/docker/daemon.json

If the file doesn't exist, you can create it. Add or modify the insecure-registries key to include localhost:5000. The file content should look like this:

{
  "insecure-registries": ["localhost:5000"]
}

Save the file and exit the editor (Ctrl+X, Y, Enter in nano).

After modifying the configuration, you need to restart the Docker daemon for the changes to take effect.

sudo systemctl restart docker

Now, you can tag the manifest list with the insecure registry address and push it. We will use the manifest list my-alpine:latest created in the first step.

docker manifest create localhost:5000/my-alpine:latest alpine:latest arm64v8/alpine:latest
docker manifest push localhost:5000/my-alpine:latest

You should see output indicating the push is successful, even though the registry is insecure.

Pushed manifest list localhost:5000/my-alpine:latest

This demonstrates how to push a manifest list to an insecure registry after configuring the Docker daemon.

Push and purge the local manifest list

In this step, we will learn how to push a manifest list and automatically remove the local copy after a successful push. This can be useful for cleaning up your local environment after pushing multi-architecture images.

The docker manifest push command has a --purge flag that removes the local manifest list after it has been successfully pushed to the registry.

First, let's ensure we have the manifest list my-alpine:latest locally. We created this in the first step. You can inspect it to confirm its existence.

docker manifest inspect my-alpine:latest

You should see the manifest list details as before.

Now, we will push this manifest list to Docker Hub again, but this time we will use the --purge flag. Remember to replace your_docker_username with your actual Docker Hub username.

docker manifest push --purge your_docker_username/my-alpine:latest

You should see output indicating the push is in progress and then a message confirming the manifest list has been purged.

Pushed manifest list your_docker_username/my-alpine:latest
Purged manifest list your_docker_username/my-alpine:latest

After the command completes, the local manifest list my-alpine:latest should no longer exist. You can verify this by trying to inspect it again.

docker manifest inspect my-alpine:latest

This time, you should see an error message indicating that the manifest list is not found.

no such manifest: my-alpine:latest

This confirms that the --purge flag successfully removed the local manifest list after pushing it to the registry.

Finally, let's clean up the local insecure registry container we started in the previous step.

docker stop registry
docker rm registry

You should see output confirming the container has been stopped and removed.

registry
registry

Summary

In this lab, we learned how to use the docker manifest command to manage multi-architecture images. We started by pulling two different architecture versions of the alpine image. Then, we used docker manifest create to combine these images into a single manifest list, allowing us to refer to them with a single name. We verified the creation of the manifest list using docker manifest inspect.

Subsequently, we explored how to push this manifest list to a Docker registry using docker manifest push. We also covered the specific case of pushing to an insecure registry by adding the --insecure flag. Finally, we learned how to push the manifest list and simultaneously remove the local copy using the --purge flag with the docker manifest push command.