Chapter 4. Working with container images

The Podman tool is designed to work with container images. You can use this tool to pull the image, inspect, tag, save, load, redistribute, and define the image signature.

4.1. Pulling container images using short-name aliases

You can use secure short names to get the image to your local system. The following procedure describes how to pull a fedora or nginx container image.

Prerequisites

  • The containers-tool meta-package is installed.

Procedure

  • Pull the container image:

    • Pull the fedora image: 

      $ 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
...

      Alias is found and the registry.fedoraproject.org/fedora image is securely pulled. The unqualified-search-registries list is not used to resolve fedora image name.

    • Pull the nginx image: 

      $ 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
...

      If no matching alias is found, you are prompted to choose one of the unqualified-search-registries list. If the selected image is pulled successfully, a new short-name alias is recorded locally, otherwise an error occurs.

Verification

  • List all images pulled to your local system: 

    $ podman images
REPOSITORY                                   TAG     IMAGE ID      CREATED        SIZE
registry.fedoraproject.org/fedora            latest  28317703decd  12 days ago    184 MB
docker.io/library/nginx                      latest  08b152afcfae  13 days ago    137 MB

Additional resources

4.2. Listing images

Use the podman images command to list images in your local storage.

Prerequisites

  • The containers-tool meta-package is installed.
  • A pulled image is available on the local system.

Procedure

  • List all images in the local storage: 

    $ podman images
REPOSITORY                           TAG     IMAGE ID      CREATED      SIZE
registry.access.redhat.com/ubi9/ubi  latest  3269c37eae33  6 weeks ago  208 MB

Additional resources

  • podman-images man page

4.3. Inspecting local images

After you pull an image to your local system and run it, you can use the podman inspect command to investigate the image. For example, use it to understand what the image does and check what software is inside the image. The podman inspect command displays information about containers and images identified by name or ID.

Prerequisites

  • The containers-tool meta-package is installed.
  • A pulled image is available on the local system.

Procedure

  • Inspect the registry.redhat.io/ubi9/ubi image: 

    $ podman inspect registry.redhat.io/ubi9/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": "ubi9-container",
        "com.redhat.license_terms": "https://www.redhat.com/...,
    "description": "The Universal Base Image is ...
    }
...

    The "Cmd" key specifies a default command to run within a container. You can override this command by specifying a command as an argument to the podman run command. This ubi9/ubi container will execute the bash shell if no other argument is given when you start it with podman run. If an "Entrypoint" key was set, its value would be used instead of the "Cmd" value, and the value of "Cmd" is used as an argument to the Entrypoint command.

Additional resources

  • podman-inspect man page

4.4. Inspecting remote images

Use the skopeo inspect command to display information about an image from a remote container registry before you pull the image to your system.

Prerequisites

  • The containers-tool meta-package is installed.

Procedure

  • The containers-tool meta-package is installed.

  • Inspect the registry.redhat.io/ubi9/ubi-init image: 

    # skopeo inspect docker://registry.redhat.io/ubi9/ubi-init
{
    "Name": "registry.redhat.io/ubi9/ubi9-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": "ubi9-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
        ...
    }
}

Additional resources

  • skopeo-inspect man page

4.5. Copying container images

You can use the skopeo copy command to copy a container image from one registry to another. For example, you can populate an internal repository with images from external registries, or sync image registries in two different locations.

Prerequisites

  • The containers-tool meta-package is installed.

Procedure

  • Copy the skopeo container image from docker://quay.io to docker://registry.example.com: 

    $ skopeo copy docker://quay.io/skopeo/stable:latest docker://registry.example.com/skopeo:latest

Additional resources

  • skopeo-copy man page

4.6. Copying image layers to a local directory

You can use the skopeo copy command to copy the layers of a container image to a local directory.

Prerequisites

  • The containers-tool meta-package is installed.

Procedure

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

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

  2. 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

Verification

  • Display the content of the /var/lib/images/nginx directory: 

    $ ls /var/lib/images/nginx
08b11a3d692c1a2e15ae840f2c15c18308dcb079aa5320e15d46b62015c0f6f3
...
4fcb23e29ba19bf305d0d4b35412625fea51e82292ec7312f9be724cb6e31ffd  manifest.json
version

Additional resources

  • skopeo-copy man page

4.7. Tagging images

Use the podman tag command to add an additional name to a local image. This additional name can consist of several parts: <registryhost>/<username>/<name>:<tag>.

Prerequisites

  • The containers-tool meta-package is installed.
  • A pulled image is available on the local system.

Procedure

  1. List all images: 

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

  2. Assign the myubi name to the registry.redhat.io/ubi9/ubi image using one of the following options:

    • The image name: 

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

    • The image ID: 

      $ podman tag 3269c37eae33 myubi

      Both commands give you the same result.

  3. List all images: 

    $ podman images
REPOSITORY                           TAG     IMAGE ID      CREATED       SIZE
registry.redhat.io/ubi9/ubi          latest  3269c37eae33  2 months ago  208 MB
localhost/myubi                      latest  3269c37eae33  2 months ago  208 MB

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

  4. Add the 9 tag to the registry.redhat.io/ubi9/ubi image using either:

    • The image name: 

      $ podman tag registry.redhat.io/ubi9/ubi myubi:9

    • The image ID: 

      $ podman tag 3269c37eae33 myubi:9

      Both commands give you the same result.

  5. List all images: 

    $ podman images
REPOSITORY                           TAG     IMAGE ID      CREATED       SIZE
registry.redhat.io/ubi9/ubi          latest  3269c37eae33  2 months ago  208 MB
localhost/myubi                      latest  3269c37eae33  2 months ago  208 MB
localhost/myubi                      9     3269c37eae33  2 months ago  208 MB

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

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

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

Additional resources

  • podman-tag man page

4.8. Saving and loading images

Use the podman save command to save an image to a container archive. You can restore it later to another container environment or send it to someone else. You can use --format option to specify the archive format. The supported formats are:

  • docker-archive
  • oci-archive
  • oci-dir (directory with oci manifest type)
  • docker-dir (directory with v2s2 manifest type)

The default format is the docker-dir format.

Use the podman load command to load an image from the container image archive into the container storage.

Prerequisites

  • The containers-tool meta-package is installed.
  • A pulled image is available on the local system.

Procedure

  1. Save the registry.redhat.io/rhel9/rsyslog image as a tarball:

    • In the default docker-dir format: 

      $ podman save -o myrsyslog.tar registry.redhat.io/rhel9/rsyslog:latest

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

      $ podman save -o myrsyslog-oci.tar --format=oci-archive registry.redhat.io/rhel9/rsyslog

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

  2. Check the file type of myrsyslog.tar: 

    $ file myrsyslog.tar
myrsyslog.tar: POSIX tar archive

  3. To load the registry.redhat.io/rhel9/rsyslog:latest image from the myrsyslog.tar: 

    $ podman load -i myrsyslog.tar
...
Loaded image(s): registry.redhat.io/rhel9/rsyslog:latest

Additional resources

  • podman-save man page

4.9. Redistributing UBI images

Use podman push command to push a UBI image to your own, or a third party, registry and share it with others. You can upgrade or add to that image from UBI dnf repositories as you like.

Prerequisites

  • The containers-tool meta-package is installed.
  • A pulled image is available on the local system.

Procedure

  1. Optional: Add an additional name to the ubi image: 

    # podman tag registry.redhat.io/ubi9/ubi registry.example.com:5000/ubi9/ubi

  2. Push the registry.example.com:5000/ubi9/ubi image from your local storage to a registry: 

    # podman push registry.example.com:5000/ubi9/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, either with Red Hat Container Certification or Red Hat OpenShift Operator Certification.

4.10. Removing images

Use the podman rmi command to remove locally stored container images. You can remove an image by its ID or name.

Prerequisites

  • The containers-tool meta-package is installed.

Procedure

  1. List all images on your local system: 

    $ podman images
REPOSITORY                           TAG     IMAGE ID      CREATED      SIZE
registry.redhat.io/rhel8/rsyslog     latest  4b32d14201de  7 weeks ago  228 MB
registry.redhat.io/ubi8/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/rhel8/rsyslog:latest  /bin/rsyslog.sh  6 seconds ago  Up 5 seconds ago          mysyslog

    To remove the registry.redhat.io/rhel8/rsyslog image, you have to stop all containers running from this image using the podman stop command. You can stop a container by its ID or name.

  3. Stop the mysyslog container: 

    $ podman stop mysyslog
7ccd6001166e9720c47fbeb077e0afd0bb635e74a1b0ede3fd34d09eaf5a52e9

  4. Remove the registry.redhat.io/rhel8/rsyslog image: 

    $ podman rmi registry.redhat.io/rhel8/rsyslog

    • To remove multiple images: 

      $ podman rmi registry.redhat.io/rhel8/rsyslog registry.redhat.io/ubi8/ubi

    • To remove all images from your system: 

      $ podman rmi -a

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

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

Additional resources

  • podman-rmi man page