Chapter 3. Working with container registries A container image registry is a repository or collection of repositories for storing container images and container-based application artifacts. The /etc/containers/registries.conf file is a system-wide configuration file containing the container image registries that can be used by the various container tools such as Podman, Buildah, and Skopeo. If the container image given to a container tool is not fully qualified, then the container tool references the registries.conf file. Within the registries.conf file, you can specify aliases for short names, granting administrators full control over where images are pulled from when not fully qualified. For example, the podman pull example.com/example_image command pulls a container image from the example.com registry to your local system as specified in the registries.conf file . 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: 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 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 display the container registries using the podman info --format command: Note The podman info command is available in Podman 4.0.0 or later. You can edit 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 USDHOME/.config/containers/registries.conf file to override the system-wide settings. 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: 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 . 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. 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" . 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 . Additional resources How to manage Linux container registries podman-pull and podman-info man pages on your system 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. To search for the postgresql-10 images in the quay.io registry, follow the steps. Prerequisites The container-tools meta-package is installed. The registry is configured. Procedure Authenticate to the registry: Search for the image: To search for a particular image on a specific registry, enter: Alternatively, to display all images provided by a particular registry, enter: To search for the image name in all registries, enter: To display the full descriptions, pass the --no-trunc option to the command. Additional resources podman-search man page on your system 3.4. Pulling images from registries Use the podman pull command to get the image to your local system. Prerequisites The container-tools meta-package is installed. Procedure Log in to the registry.redhat.io registry: Pull the registry.redhat.io/ubi9/ubi container image: Verification List all images pulled to your local system: Additional resources podman-pull man page on your system 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 example, 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: 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 USDHOME/.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 Container image short names in Podman

Commands:
podman pull <registry>[:<port>]/[<namespace>/]<name>:<tag>
podman info -f json | jq '.registries["search"]' [ "registry.access.redhat.com", "registry.redhat.io", "docker.io" ]
unqualified-search-registries = ["registry.access.redhat.com", "registry.redhat.io", "docker.io"] short-name-mode = "enforcing"
[[registry]] location="localhost:5000" insecure=true
[[registry]] location = "registry.example.org" blocked = true
[[registry]] location = "registry.example.org" prefix="registry.example.org/namespace" blocked = true
[[registry]] location = "registry.example.org" prefix="registry.example.org/namespace/image" blocked = true
[[registry]] location="registry.example.com" [[registry.mirror]] location="mirror-1.com" [[registry.mirror]] location="mirror-2.com"
podman login quay.io
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
podman search quay.io/
podman search postgresql-10
podman login registry.redhat.io Username: <username> Password: <password> Login Succeeded!
podman pull registry.redhat.io/ubi9/ubi
podman images REPOSITORY TAG IMAGE ID CREATED SIZE registry.redhat.io/ubi9/ubi latest 3269c37eae33 7 weeks ago 208 MB
unqualified-search-registries=["registry.fedoraproject.org", "quay.io"] [aliases] "fedora"="registry.fedoraproject.org/fedora"