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:
# 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/ubi8/ubi container image is identified by:
-
Registry server (
registry.redhat.io) -
Namespace (
ubi8) -
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 ubi8/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 display the container registries using the podman info --format command:
$ podman info -f json | jq '.registries["search"]' [ "registry.access.redhat.com", "registry.redhat.io", "docker.io" ]
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 $HOME/.config/containers/registries.conf file to override the system-wide settings.
unqualified-search-registries = ["registry.access.redhat.com", "registry.redhat.io", "docker.io"] short-name-mode = "permissive"
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=falseoption in Podman. Second, you can setinsecure=truein theregistries.conffile:[[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:latestcommand will be blocked, because the specified prefix is matched.[[registry]] location = "registry.example.org" prefix="registry.example.org/namespace" blocked = true
Noteprefixis optional, default value is the same as thelocationvalue.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:latestcommand, themirror-1.comis tried first, thenmirror-2.com.[[registry]] location="registry.example.com" [[registry.mirror]] location="mirror-1.com" [[registry.mirror]] location="mirror-2.com"
Additional resources
- How to manage Linux container registries
-
The
podman-pullandpodman-infoman 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.
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-toolsmodule is installed. - The registry is configured.
Procedure
Authenticate to the registry:
# podman login quay.ioSearch 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 ... 0Alternatively, 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-10To display the full descriptions, pass the
--no-truncoption to the command.
Additional resources
-
podman-searchman 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-toolsmodule is installed.
Procedure
Log in to the registry.redhat.io registry:
$ podman login registry.redhat.io Username: <username> Password: <password> Login Succeeded!Pull the registry.redhat.io/ubi8/ubi container image:
$ podman pull registry.redhat.io/ubi8/ubi
Verification
List all images pulled to your local system:
$ podman images REPOSITORY TAG IMAGE ID CREATED SIZE registry.redhat.io/ubi8/ubi latest 3269c37eae33 7 weeks ago 208 MB
Additional resources
-
podman-pullman 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 ubi8 instead of registry.access.redhat.com/ubi8: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 ubi8 directly resolves to the right image, that is registry.access.redhat.com/ubi8: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.conffile (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.conffile has precedence over theregistries.conffile 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
