Chapter 4. Manage container images

Procedure

1. Optional: Log in to the registry. For example, to log in to registry.redhat.io:

   $ podman login registry.redhat.io

   Username: <username>
   Password: <password>
   Login Succeeded!

2. Pull an image by using its fully qualified name. For example, to pull the registry.redhat.io/ubi10/ubi image:

   $ podman pull registry.redhat.io/ubi10/ubi

   Pull an image by its fully qualified name. While short names are convenient, there is increased risk of mistakenly getting the wrong container image. Which image is actually pulled is dependent on many factors, including if an image matching that name was pulled previously on the system. When you use short names, there is always an inherent risk of spoofing.

3. Optional: Pull an image by using a short-name alias.

   1. If a matching alias is configured, Podman resolves the short name and pulls the image from the aliased registry:

      $ podman pull fedora

      Resolved "fedora" as an alias (/etc/containers/registries.conf.d/000-shortnames.conf).

      Trying to pull registry.fedoraproject.org/fedora:latest…
      ...
      Storing signatures
      ...
      The alias is found and the registry.fedoraproject.org/fedora image is securely pulled. The unqualified-search-registries list is not used to resolve the fedora image name.

   2. If no matching alias is found, you are prompted to choose one of the registries in the unqualified-search-registries list:

      $ podman pull nginx

      ? Please select an image:
      registry.access.redhat.com/nginx:latest
      registry.redhat.io/nginx:latest
        ▸ docker.io/library/nginx:latest
      ✔ docker.io/library/nginx:latest
      Trying to pull docker.io/library/nginx:latest…
      ...
      Storing signatures
      ...

4. Once an image is pulled successfully by a short name, the system continues to pull that image by default and will not prompt you to select one.

Procedure

1. List all images in the local storage:

   $ podman images

   REPOSITORY                    TAG     IMAGE ID      CREATED      SIZE
   registry.redhat.io/ubi10/ubi  latest  3269c37eae33  7 weeks ago  208 MB

2. Inspect an image in your local storage. For example, to inspect the registry.redhat.io/ubi10/ubi image:

   $ podman inspect registry.redhat.io/ubi10/ubi

   …
    "Cmd": [
           "/bin/bash"
       ],
       "Labels": {
           "architecture": "x86_64",
           "build-date": "2020-12-10T01:59:40.343735",
           "com.redhat.build-host": "cpt-1002.osbs.prod.upshift.rdu2.redhat.com",
           "com.redhat.component": "ubi10-container",
           "com.redhat.license_terms": "https://www.redhat.com/...,
       "description": "The Universal Base Image is ...
       }
   …

   The podman inspect command displays information about containers and images identified by name or ID. The Cmd key specifies a default command that will be executed in the container if there is not one specified in the run command line. You can override this command by specifying a command as an argument to the podman run command.

   This ubi10/ubi container runs the bash shell if no other argument is given when you start it with podman run. If an Entrypoint key was set, its value can be used instead of the Cmd value, and the value of Cmd is used as an argument to the Entrypoint command.

3. Inspect an image in a remote registry, before you pull it. For example, to inspect the registry.redhat.io/ubi10/ubi-init image:

   $ skopeo inspect docker://registry.redhat.io/ubi10/ubi-init

   {
       "Name": "registry.redhat.io/ubi10/ubi-init",
       "Digest": "sha256:c6d1e50ab...",
       "RepoTags": [
           ...
           "latest"
       ],
      "Created": "2020-12-10T07:16:37.250312Z",
       "DockerVersion": "1.13.1",
       "Labels": {
           "architecture": "x86_64",
           "build-date": "2020-12-10T07:16:11.378348",
           "com.redhat.build-host": "cpt-1007.osbs.prod.upshift.rdu2.redhat.com",
           "com.redhat.component": "ubi10-init-container",
           "com.redhat.license_terms": "https://www.redhat.com/en/about/red-hat-end-user-license-agreements#UBI",
           "description": "The Universal Base Image Init is designed to run an init system as PID 1 for running multi-services inside a container
           ...
       }
   }

4. Create the /var/lib/images/nginx directory:

   $ mkdir -p /var/lib/images/nginx

5. Copy the layers of the docker://docker.io/nginx:latest image to the newly created directory:

   $ skopeo copy docker://docker.io/nginx:latest dir:/var/lib/images/nginx

Procedure

1. Assign the myubi name to the registry.redhat.io/ubi10/ubi image by using one of the following options:

   • The image name:

     $ podman tag registry.redhat.io/ubi10/ubi myubi

   • The image ID:

     $ podman tag 3269c37eae33 myubi

     Both commands give you the same result.

2. Add the 10 tag to the registry.redhat.io/ubi10/ubi image by using either:

   • The image name:

     $ podman tag registry.redhat.io/ubi10/ubi myubi:10

   • The image ID:

     $ podman tag 3269c37eae33 myubi:10

     Both commands give you the same result. If no version tag is specified after the :, it defaults to the latest.

3. Optional: Add an additional name that includes the registry you want to push the image to: $ podman tag registry.redhat.io/ubi10/ubi registry.example.com:5000/ubi10/ubi

4. Push the registry.example.com:5000/ubi10/ubi image from your local storage to a registry: $ podman push registry.example.com:5000/ubi10/ubi

   Important

   While there are few restrictions on how you use these images, there are some restrictions about how you can refer to them. For example, you cannot call those images Red Hat certified or Red Hat supported unless you certify it through the Red Hat Partner Connect Program (https://connect.redhat.com), either with Red Hat Container Certification or Red Hat OpenShift Operator Certification.

Verification

1. List all images:

   $ podman images

   REPOSITORY                    TAG     IMAGE ID      CREATED       SIZE
   registry.redhat.io/ubi10/ubi  latest  3269c37eae33  7 weeks ago  208 MB
   localhost/myubi               latest  3269c37eae33  7 weeks ago  208 MB
   localhost/myubi               10      3269c37eae33  7 weeks ago  208 MB

   Notice that the default tag is the latest. You can see all the image names are assigned to the single image ID 3269c37eae33.

2. After tagging the registry.redhat.io/ubi10/ubi image, you have three options to run the container:

   • by ID (3269c37eae33)
   • by name (localhost/myubi:latest)

   • by name (localhost/myubi:10)

     For more information, see podman-tag(1) man page on your system.

Procedure

1. Save the registry.redhat.io/rhel10/support-tools image as a tarball, in one of the following formats:

   • In the default docker-archive format:

     $ podman save -o mysupport-tools.tar registry.redhat.io/rhel10/support-tools:latest

   • In the oci-archive format, by using the --format option:

     $ podman save -o mysupport-tools-oci.tar --format=oci-archive registry.redhat.io/rhel10/support-tools

     The mysupport-tools.tar and mysupport-tools-oci.tar archives are stored in your current directory. The next steps are performed with the mysupport-tools.tar tarball.

2. Check the file type of mysupport-tools.tar:

   $ file mysupport-tools.tar
   mysupport-tools.tar: POSIX tar archive

3. Load the registry.redhat.io/rhel10/support-tools:latest image from the mysupport-tools.tar archive:

   $ podman load -i mysupport-tools.tar

   Loaded image(s): registry.redhat.io/rhel10/support-tools:latest

   For more information, see podman-save(1) and podman-load(1) man pages on your system.

Procedure

1. Create Containerfiles for each target architecture.

2. Do one of the following:

   1. Build images for each architecture. For example, this can be done in one command:

      $ podman build --platform linux/arm64,linux/amd64 --manifest <registry>/<image>:<version> .

      • The --platform linux/arm64,linux/amd64 option specifies the target platforms for which the container image is being built.
      • The --manifest <registry>/<image> option creates a manifest list with the specified name, that is <registry>/<image>, and adds the newly-built images to them.

   2. Create the images separately and then add them to a manifest:

      1. Create image:

         $ podman build --platform linux/amd64 -t <registry>/<image>:<version> .

         $ podman build --platform linux/arm64 -t <registry>/<image>:<version> .

      2. Initialize an empty manifest list:

         $ podman manifest create <registry>/<image>:<version>

      3. Add the platform images to the manifest list:

         $ podman manifest add <registry>/<image>:<version> <registry>/<image>:<version>-amd64

         $ podman manifest add <registry>/<image>:<version> <registry>/<image>:<version>-arm64

   3. Optional: Remove items from the manifest list by using the podman manifest remove <manifest_list> <digest_ID> command, where <digest_ID> is the SHA-256 checksum of the container image. For example:

      $ podman manifest remove <registry>/<image> sha256:cb8a924afdf…​.

3. Push the manifest list to the registry:

   $ podman manifest push <registry>/<image>:<version>

Procedure

1. List all images on your local system:

   $ podman images

   REPOSITORY                               TAG     IMAGE ID      CREATED      SIZE
   registry.redhat.io/rhel10/support-tools  latest  4b32d14201de  7 weeks ago  228 MB
   registry.redhat.io/ubi10/ubi             latest  3269c37eae33  7 weeks ago  208 MB
   localhost/myubi                          X.Y     3269c37eae33  7 weeks ago  208 MB

2. List all containers:

   $ podman ps -a

   CONTAINER ID  IMAGE                       COMMAND       CREATED        STATUS      PORTS  NAMES
   7ccd6001166e  registry.redhat.io/rhel10/support-tools:latest  usr/bin/bash  6 seconds ago  Up 5 seconds ago         my-support-tools

3. Stop the my-support-tools container:

   $ podman stop my-support-tools

   7ccd6001166e9720c47fbeb077e0afd0bb635e74a1b0ede3fd34d09eaf5a52e9

4. Remove stopped containers that reference the image. For each image using the image to be removed, remove it with the command:

   $ podman rm <container name|container id>

   If you do not remove the containers, you can still remove the image by forcing the removal. See next step.

5. Do one of the following:

   1. Remove the registry.redhat.io/rhel10/support-tools image:

      $ podman rmi registry.redhat.io/rhel10/support-tools

      If there are still containers referencing the image, even if not running, it will generate an error. You can force the removal (as well as all containers linked to the image) with:

      $ podman rmi -f registry.redhat.io/rhel10/support-tools

   2. To remove multiple images:

      $ podman rmi registry.redhat.io/rhel10/support-tools \ registry.redhat.io/ubi10/ubi

   3. To remove all images from your system:

      $ podman rmi -a

   4. To remove images that have multiple names (tags) associated with them, add the -f option to remove them:

      $ podman rmi -f 1de7d7b3f531
      1de7d7b3f531...