How to use docker scout stream command to manage streams

Introduction

In this lab, you will learn how to manage streams using the docker scout stream command. Streams are essentially collections of images, and understanding how to interact with them is crucial for organizing and managing your Docker images effectively.

You will begin by learning how to list existing streams to see what image collections are available. Then, you will explore how to list the specific images contained within a particular stream. Finally, you will learn how to record an image to a stream for a specific platform, allowing you to associate images with their respective streams and platforms.

Skills Graph

List existing streams

In this step, you will learn how to list existing streams in Docker. Streams are essentially repositories or collections of images. Listing streams helps you see what image collections are available to you.

First, let's use the docker images command to list all available images. This command shows you the images that are currently downloaded on your system.

docker images

You should see output similar to this, although the specific images will vary depending on what has been pulled:

REPOSITORY    TAG       IMAGE ID       CREATED        SIZE
ubuntu        latest    d621e9f15c2f   2 weeks ago    72.8MB
hello-world   latest    d2c94e258dcb   2 months ago   13.3kB

The REPOSITORY column in the output represents the stream name. The TAG column represents a specific version within that stream.

To list only the unique stream names (repositories), you can process the output of docker images. We can use command-line tools like awk and sort to achieve this.

docker images | awk '{print $1}' | sort -u

Let's break down this command:

• docker images: This command lists all images.
• |: This is a pipe, which sends the output of the command on the left as input to the command on the right.
• awk '{print $1}': awk is a powerful text processing tool. {print $1} tells awk to print the first column of each line of the input. In the docker images output, the first column is the REPOSITORY.
• |: Another pipe to send the output of awk to sort.
• sort -u: sort sorts the input lines alphabetically. -u stands for unique, which removes duplicate lines. This gives us a list of unique repository names, which are our streams.

The output will be a list of unique repository names, like this:

REPOSITORY
hello-world
ubuntu

This command effectively lists the existing streams (repositories) that have images downloaded on your system.

List images of a specific stream

In the previous step, you learned how to list all existing streams (repositories). Now, you will learn how to list the images belonging to a specific stream. This is useful when you want to see the different versions (tags) of a particular image.

To list images of a specific stream, you can use the docker images command followed by the stream name. For example, to list all images in the ubuntu stream, you would use:

docker images ubuntu

Before running this command, let's make sure the ubuntu image is available on your system. If it's not, you can pull it using the docker pull command.

docker pull ubuntu

You should see output indicating that the image is being downloaded.

Using default tag: latest
latest: Pulling from library/ubuntu
...
Status: Downloaded newer image for ubuntu:latest
docker.io/library/ubuntu:latest

Now that the ubuntu image is available, you can list the images in the ubuntu stream:

docker images ubuntu

The output will show the images belonging to the ubuntu stream. If you only pulled the latest tag, you will see something like this:

REPOSITORY   TAG       IMAGE ID       CREATED        SIZE
ubuntu       latest    d621e9f15c2f   2 weeks ago    72.8MB

If you had other tags of ubuntu downloaded, they would also be listed here.

You can replace ubuntu with any other stream name you saw in the output of docker images from the previous step to list the images in that specific stream. For example, to list images in the hello-world stream:

docker images hello-world

This command will show you the images available for the hello-world stream.

Record an image to a stream for a specific platform

In this step, you will learn how to "record" an image to a stream for a specific platform. In Docker terminology, this is typically done by tagging an existing image with a new name that includes the desired stream and potentially platform information. Tagging an image essentially creates a new pointer to an existing image layer, allowing you to refer to the same image with a different name and tag.

The basic command for tagging an image is docker tag. The syntax is:

docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]

• SOURCE_IMAGE[:TAG]: This is the name and optional tag of the existing image you want to tag.
• TARGET_IMAGE[:TAG]: This is the new name and optional tag you want to assign to the image. The TARGET_IMAGE part represents the stream name.

Let's use the ubuntu image we pulled in the previous step. We will tag it with a new stream name, for example, myubuntu.

First, let's verify the existing ubuntu image and its ID:

docker images ubuntu

You will see output similar to this, noting the IMAGE ID:

REPOSITORY   TAG       IMAGE ID       CREATED        SIZE
ubuntu       latest    d621e9f15c2f   2 weeks ago    72.8MB

Now, let's tag the ubuntu:latest image with the new stream name myubuntu and tag v1.0:

docker tag ubuntu:latest myubuntu:v1.0

This command doesn't produce much output if successful. It simply creates the new tag.

Now, let's list the images again to see the newly tagged image:

docker images

You should now see both the original ubuntu:latest image and the new myubuntu:v1.0 image, both pointing to the same IMAGE ID:

REPOSITORY   TAG       IMAGE ID       CREATED        SIZE
myubuntu     v1.0      d621e9f15c2f   2 weeks ago    72.8MB
ubuntu       latest    d621e9f15c2f   2 weeks ago    72.8MB
hello-world  latest    d2c94e258dcb   2 months ago   13.3kB

Notice that myubuntu:v1.0 has the same IMAGE ID as ubuntu:latest. This confirms that myubuntu:v1.0 is just a new reference to the same underlying image data.

While the docker tag command itself doesn't explicitly handle platforms in the tagging process, the image itself might be built for a specific platform. When you pull an image, Docker typically pulls the image for the architecture of your system. If you need to work with images for different platforms, you would typically use tools like docker buildx to build multi-platform images or specify the platform during the pull operation (e.g., docker pull --platform linux/amd64 ubuntu). However, for the purpose of "recording" an existing image to a stream, the docker tag command is the standard way to create a new reference to that image within a different stream name.

Summary

In this lab, you learned how to manage streams using the docker scout stream command. You began by understanding how to list existing streams, which are essentially repositories or collections of images. You used the docker images command to see all downloaded images and then processed the output with awk and sort -u to extract and list the unique stream names (repositories).

You also learned how to list the images belonging to a specific stream and how to record an image to a stream for a specific platform. These steps demonstrate fundamental operations for organizing and managing your Docker images within the context of streams.