Menu Close

Chapter 3. 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.

3.1. Container registries

A container registry is a repository or collection of repositories for storing container images and container-based application artifacts. The registries that Red Hat provides are:

  • registry.redhat.io (requires authentication)
  • registry.access.redhat.com (requires no authentication)
  • registry.connect.redhat.com (holds Red Hat Partner Connect program images)

To get container images from a remote registry, such as Red Hat’s own container registry, and add them to your local system, use the podman pull command: 

# podman pull <registry>[:<port>]/[<namespace>/]<name>:<tag>

where <registry>[:<port>]/[<namespace>/]<name>:<tag> is the name of the container image.

For example, the registry.redhat.io/ubi9/ubi container image is identified by:

  • Registry server (registry.redhat.io)
  • Namespace (ubi9)
  • Image name (ubi)

If there are multiple versions of the same image, add a tag to explicitly specify the image name. By default, Podman uses the :latest tag, for example ubi9/ubi:latest.

Some registries also use <namespace> to distinguish between images with the same <name> owned by different users or organizations. For example:

NamespaceExamples (<namespace>/<name>)

organization

redhat/kubernetes, google/kubernetes

login (user name)

alice/application, bob/application

role

devel/database, test/database, prod/database

For details on the transition to registry.redhat.io, see Red Hat Container Registry Authentication. Before you can pull containers from registry.redhat.io, you need to authenticate using your RHEL Subscription credentials.

3.2. Configuring container registries

You can find the list of container registries in the registries.conf configuration file. As a root user, edit the /etc/containers/registries.conf file to change the default system-wide search settings.

As a user, create the $HOME/.config/containers/registries.conf file to override the system-wide settings. 

unqualified-search-registries = ["registry.fedoraproject.org", "registry.access.redhat.com", "docker.io"]

By default, the podman pull and podman search commands search for container images from registries listed in the unqualified-search-registries list in the given order.

Configuring a local container registry

You can configure a local container registry without the TLS verification. You have two options on how to disable TLS verification. First, you can use the --tls-verify=false option in Podman. Second, you can set insecure=true in the registries.conf file: 

[[registry]]
location="localhost:5000"
insecure=true
Blocking a registry, namespace, or image

You can define registries the local system is not allowed to access. You can block a specific registry by setting blocked=true. 

[[registry]]
location = "registry.example.org"
blocked = true

You can also block a namespace by setting the prefix to prefix="registry.example.org/namespace". For example, pulling the image using the podman pull registry. example.org/example/image:latest command will be blocked, because the specified prefix is matched. 

[[registry]]
location = "registry.example.org"
prefix="registry.example.org/namespace"
blocked = true
Note

prefix is optional, default value is the same as the location value.

You can block a specific image by setting prefix="registry.example.org/namespace/image". 

[[registry]]
location = "registry.example.org"
prefix="registry.example.org/namespace/image"
blocked = true
Mirroring registries

You can set a registry mirror in cases you cannot access the original registry. For example, you cannot connect to the internet, because you work in a highly-sensitive environment. You can specify multiple mirrors that are contacted in the specified order. For example, when you run podman pull registry.example.com/myimage:latest command, the mirror-1.com is tried first, then mirror-2.com. 

[[registry]]
location="registry.example.com"
[[registry.mirror]]
location="mirror-1.com"
[[registry.mirror]]
location="mirror-2.com"

Additional resources

3.3. Searching for container images

Using the podman search command you can search selected container registries for images. You can also search for images in the Red Hat Container Catalog. The Red Hat Container Registry includes the image description, contents, health index, and other information.

Note

The podman search command is not a reliable way to determine the presence or existence of an image. The podman search behavior of the v1 and v2 Docker distribution API is specific to the implementation of each registry. Some registries may not support searching at all. Searching without a search term only works for registries that implement the v2 API. The same holds for the docker search command.

This section explains how to search for the postgresql-10 images in the quay.io registry.

Prerequisites

  • The registry is configured.

Procedure

  1. Authenticate to the registry: 

    # podman login quay.io

  2. Search for the image:

    • To search for a particular image on a specific registry, enter: 

      podman search quay.io/postgresql-10
INDEX       NAME                                           DESCRIPTION           STARS   OFFICIAL   AUTOMATED
redhat.io   registry.redhat.io/rhel8/postgresql-10         This container image ...  0
redhat.io   registry.redhat.io/rhscl/postgresql-10-rhel7   PostgreSQL is an  ...     0

    • Alternatively, to display all images provided by a particular registry, enter: 

      # podman search quay.io/

    • To search for the image name in all registries, enter: 

      # podman search postgresql-10

      To display the full descriptions, pass the --no-trunc option to the command.

Additional resources

  • podman-search man page

3.4. Pulling images from registries

Use the podman pull command to get the image to your local system.

Procedure

  1. Log in to the registry.redhat.io registry: 

    $ podman login registry.redhat.io
Username: username
Password: **********
Login Succeeded!

  2. Pull the registry.redhat.io/ubi9/ubi container image: 

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

Verification steps

  • List all images pulled to your local system: 

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

Additional resources

  • podman-pull man page

3.5. Configuring short-name aliases

Red Hat recommends always to pull an image by its fully-qualified name. However, it is customary to pull images by short names. For instance, you can use ubi9 instead of registry.access.redhat.com/ubi9:latest.

The registries.conf file allows to specify aliases for short names, giving administrators full control over where images are pulled from. Aliases are specified in the [aliases] table in the form "name" = "value". You can see the lists of aliases in the /etc/containers/registries.conf.d directory. Red hat ships a set of aliases in this directory. For example, podman pull ubi9 directly resolves to the right image, that is registry.access.redhat.com/ubi9:latest.

For example: 

unqualified-search-registries=["registry.fedoraproject.org", “quay.io"]

[aliases]
"fedora"="registry.fedoraproject.org/fedora"

The short-names modes are:

  • enforcing: If no matching alias is found during the image pull, Podman prompts the user to choose one of the unqualified-search registries. If the selected image is pulled successfully, Podman automatically records a new short-name alias in the $HOME/.cache/containers/short-name-aliases.conf file (rootless user) or in the /var/cache/containers/short-name-aliases.conf (root user). If the user cannot be prompted (for example, stdin or stdout are not a TTY), Podman fails. Note that the short-name-aliases.conf file has precedence over the registries.conf file if both specify the same alias.
  • permissive: Similar to enforcing mode, but Podman does not fail if the user cannot be prompted. Instead, Podman searches in all unqualified-search registries in the given order. Note that no alias is recorded.
  • disabled: All unqualified-search registries are tried in a given order, no alias is recorded.
Note

Red Hat recommends using fully qualified image names including registry, namespace, image name, and tag. When using short names, there is always an inherent risk of spoofing. Add registries that are trusted, that is, registries that do not allow unknown or anonymous users to create accounts with arbitrary names. For example, a user wants to pull the example container image from example.registry.com registry. If example.registry.com is not first in the search list, an attacker could place a different example image at a registry earlier in the search list. The user would accidentally pull and run the attacker image rather than the intended content.

Additional resources

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

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

3.7. Listing images

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

Prerequisites

  • 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

3.8. 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 on containers and images identified by name or ID.

Prerequisites

  • 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

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

Procedure

  • 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

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

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

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

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

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

  • 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 either:

    • 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

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

  • 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

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

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

3.15. Default verification of the image signatures

The policy YAML files for the Red Hat Container Registries /etc/containers/registries.d/registry.access.redhat.com.yaml and /etc/containers/registries.d/registry.redhat.io.yaml files are included in the containers-common package which is included in the container-tools:latest module. Use the podman image trust command to verify the container image signatures on RHEL.

Procedure

  1. Update an existing trust scope for the registry.access.redhat.com: 

    # podman image trust set -f /etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release registry.access.redhat.com

  2. Optional. To verify the trust policy configuration, display the /etc/containers/policy.json file: 

    ...
"transports": {
  "docker": {
      "registry.access.redhat.com": [
       {
         "type": "signedBy",
         "keyType": "GPGKeys",
         "keyPath": "/etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release"
       }
     ]
},
...

  3. Update an existing trust scope for the registry.redhat.io: 

    # podman image trust set -f /etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release registry.redhat.io

  4. Optional. To verify the trust policy configuration, display the /etc/containers/policy.json file: 

    ...
"transports": {
 "docker": {
      "registry.access.redhat.com": [
      {
        "type": "signedBy",
        "keyType": "GPGKeys",
        "keyPath": "/etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release"
      }
    ],
     "registry.redhat.io": [
     {
        "type": "signedBy",
        "keyType": "GPGKeys",
        "keyPath": "/etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release"
     }
   ]
},
...

Additional resources

  • podman-image-trust man page

3.16. Removing images

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

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