Home
Products
Red Hat Enterprise Linux
10
Building, running, and managing containers
Chapter 4. Working with container images

Chapter 4. Working with container images

Manage container images by using the Podman tool. You can use this tool to pull the image, inspect, tag, save, load, redistribute, and define the image signature.

4.1. Pulling images from registries
Copy link

Download container images from remote registries to your local system by using the podman pull command. This makes the image available for creating and running containers.

Prerequisites

The container-tools meta-package is installed.

Procedure

$ podman login registry.redhat.io
Username: <username>
Password: <password>
Login Succeeded!

Pull the registry.redhat.io/ubi10/ubi container image:
```
$ podman pull registry.redhat.io/ubi10/ubi
```

Verification

List all images pulled to your local system:

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

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

4.2. Pulling container images using short-name aliases
Copy link

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 container-tools 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

4.3. Listing images
Copy link

You can list locally stored container images on by using Podman to verify version availability and manage system storage. Viewing the image list ensures you select the appropriate foundation for your workloads while maintaining visibility into your local environment.

Prerequisites

The container-tools 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/ubi10/ubi  latest  3269c37eae33  6 weeks ago  208 MB

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

4.4. Inspecting local images
Copy link

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 container-tools meta-package is installed.
A pulled image is available on the local system.

Procedure

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 "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 ubi10/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.

4.5. Inspecting remote images
Copy link

Use the skopeo inspect command to display information about an image from a remote container registry before you pull the image to your system. This reveals details such as the default command, environment variables, and architecture.

Prerequisites

The container-tools meta-package is installed.

Procedure

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

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

For more information, see the skopeo-inspect(1) man page on your system.

4.6. Copying container images
Copy link

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 container-tools 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
```
Refer to skopeo-copy(1) man page on your system for more information.

4.7. Copying image layers to a local directory
Copy link

Copying container image layers to a local directory by using Skopeo to audit image contents or troubleshoot file system changes. Storing layers locally enables you to inspect the image structure and verify security compliance without the need to deploy the container.

Prerequisites

The container-tools meta-package is installed.

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

Refer to skopeo-copy(1) man page on your system for more information.

4.8. Tagging images
Copy link

Assign additional names or tags to local images by using the podman tag command. Tagging helps organize images and prepare them for pushing to specific registries.

This additional name can consist of several parts: <registryhost>/<username>/<name>:<tag>.

Prerequisites

The container-tools meta-package is installed.
A pulled image is available on the local system.

Procedure

List all images:

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

Assign the myubi name to the registry.redhat.io/ubi10/ubi image 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.

List all images:

$ podman images
REPOSITORY                           TAG     IMAGE ID      CREATED       SIZE
registry.redhat.io/ubi10/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 10 tag to the registry.redhat.io/ubi10/ubi image 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.

Verification

List all images:

$ podman images
REPOSITORY                           TAG     IMAGE ID      CREATED       SIZE
registry.redhat.io/ubi10/ubi          latest  3269c37eae33  2 months ago  208 MB
localhost/myubi                      latest  3269c37eae33  2 months ago  208 MB
localhost/myubi                      10     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/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.

4.9. Building multi-architecture images
Copy link

Build multi-architecture container images by using Podman on RHEL to ensure your applications run consistently across diverse hardware platforms. This approach allows a single image manifest to support multiple architectures, without the requirement of unique builds for each environment.

Prerequisites

The container-tools meta-package is installed.

Procedure

Create Containerfiles for each architecture you want to support.
Build images for each architecture. For example:
```
$ podman build --platform linux/arm64,linux/amd64 --manifest <registry>/<image> .
```
- 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. A manifest list is a collection of image manifests, each one targeting a different architecture.
Push the manifest list to the registry:
```
$ podman manifest push <registry>/<image>
```
This manifest list acts as a single entry point for pulling the multi-architecture container.
As a result, you can pull the appropriate container image for your platform, based on a single manifest list.
You can also 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….

Verification

Display the manifest list:
```
$ podman manifest inspect <registry>/<image>
```
Refer to the podman-build(1) and podman-manifest(1) man page on your system for more information.

4.10. Saving and loading images
Copy link

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 the --format option to specify the archive format. The supported formats are:

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

The default format is the docker-archive format.

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

Prerequisites

The container-tools meta-package is installed.
A pulled image is available on the local system.

Procedure

Save the registry.redhat.io/rhel10/support-tools image as a tarball:
- In the default docker-archive format:
  $ podman save -o mysupport-tools.tar registry.redhat.io/rhel10/support-tools:latest
- In the oci-archive format, 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.

Check the file type of mysupport-tools.tar:

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

To load the registry.redhat.io/rhel10/support-tools:latest image from the mysupport-tools.tar:
```
$ podman load -i mysupport-tools.tar
...
Loaded image(s): registry.redhat.io/rhel10/support-tools:latest
```
For more information, see the podman-save(1) and podman-load(1) man pages on your system.

4.11. Redistributing UBI images
Copy link

Share your custom UBI-based images by pushing them to a registry with the podman push command. This enables others to download and use your modified images.

Prerequisites

The container-tools meta-package is installed.
A pulled image is available on the local system.

Procedure

Optional: Add an additional name to the ubi image:

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

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, either with Red Hat Container Certification or Red Hat OpenShift Operator Certification.

4.12. Removing images
Copy link

Delete unused container images from local storage using the podman rmi command. Removing old images frees up disk space on your system.

Prerequisites

The container-tools meta-package is installed.

Procedure

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

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

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

Stop the my-support-tools container:

$ podman stop my-support-tools
7ccd6001166e9720c47fbeb077e0afd0bb635e74a1b0ede3fd34d09eaf5a52e9

Remove the registry.redhat.io/rhel10/support-tools image:
```
$ podman rmi registry.redhat.io/rhel10/support-tools
```
- To remove multiple images:
  $ podman rmi registry.redhat.io/rhel10/support-tools registry.redhat.io/ubi10/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...

Verification

List all images by using the podman images command to verify that container images were removed.

Chapter 4. Working with container images

4.1. Pulling images from registries
Copy link

4.2. Pulling container images using short-name aliases
Copy link

4.3. Listing images
Copy link

4.4. Inspecting local images
Copy link

4.5. Inspecting remote images
Copy link

4.6. Copying container images
Copy link

4.7. Copying image layers to a local directory
Copy link

4.8. Tagging images
Copy link

4.9. Building multi-architecture images
Copy link

4.10. Saving and loading images
Copy link

4.11. Redistributing UBI images
Copy link

4.12. Removing images
Copy link

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

Chapter 4. Working with container images

4.1. Pulling images from registriesCopy linkLink copied to clipboard!

4.2. Pulling container images using short-name aliasesCopy linkLink copied to clipboard!

4.3. Listing imagesCopy linkLink copied to clipboard!

4.4. Inspecting local imagesCopy linkLink copied to clipboard!

4.5. Inspecting remote imagesCopy linkLink copied to clipboard!

4.6. Copying container imagesCopy linkLink copied to clipboard!

4.7. Copying image layers to a local directoryCopy linkLink copied to clipboard!

4.8. Tagging imagesCopy linkLink copied to clipboard!

4.9. Building multi-architecture imagesCopy linkLink copied to clipboard!

4.10. Saving and loading imagesCopy linkLink copied to clipboard!

4.11. Redistributing UBI imagesCopy linkLink copied to clipboard!

4.12. Removing imagesCopy linkLink copied to clipboard!

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

4.1. Pulling images from registries
Copy link

4.2. Pulling container images using short-name aliases
Copy link

4.3. Listing images
Copy link

4.4. Inspecting local images
Copy link

4.5. Inspecting remote images
Copy link

4.6. Copying container images
Copy link

4.7. Copying image layers to a local directory
Copy link

4.8. Tagging images
Copy link

4.9. Building multi-architecture images
Copy link

4.10. Saving and loading images
Copy link

4.11. Redistributing UBI images
Copy link

4.12. Removing images
Copy link