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:
Namespace | Examples (<namespace>/<name>) |
---|---|
organization |
|
login (user name) |
|
role |
|
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 setinsecure=true
in theregistries.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 thepodman 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
Noteprefix
is optional, default value is the same as thelocation
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, themirror-1.com
is tried first, thenmirror-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.
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
Authenticate to the registry:
# podman login quay.io
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
Log in to the registry.redhat.io registry:
$ podman login registry.redhat.io Username: username Password: ********** Login Succeeded!
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 theshort-name-aliases.conf
file has precedence over theregistries.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.
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. Theunqualified-search-registries
list is not used to resolvefedora
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 thepodman run
command. This ubi9/ubi container will execute the bash shell if no other argument is given when you start it withpodman 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 fromdocker://quay.io
todocker://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
Create the
/var/lib/images/nginx
directory:$ mkdir -p /var/lib/images/nginx
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
List all images:
$ podman images REPOSITORY TAG IMAGE ID CREATED SIZE registry.redhat.io/ubi9/ubi latest 3269c37eae33 7 weeks ago 208 MB
Assign the
myubi
name to theregistry.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.
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.Add the
9
tag to theregistry.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.
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
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
andmyrsyslog-oci.tar
archives are stored in your current directory. The next steps are performed with themyrsyslog.tar
tarball.
Check the file type of
myrsyslog.tar
:$ file myrsyslog.tar myrsyslog.tar: POSIX tar archive
To load the
registry.redhat.io/rhel9/rsyslog:latest
image from themyrsyslog.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
Optional: Add an additional name to the
ubi
image:# podman tag registry.redhat.io/ubi9/ubi registry.example.com:5000/ubi9/ubi
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
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
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" } ] }, ...
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
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
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
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 thepodman stop
command. You can stop a container by its ID or name.Stop the
mysyslog
container:$ podman stop mysyslog 7ccd6001166e9720c47fbeb077e0afd0bb635e74a1b0ede3fd34d09eaf5a52e9
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