If you’re working with container images on Red Hat Enterprise Linux 7.1 or Red Hat Enterprise Linux Atomic Host, you might have noticed that the search and pull behavior of the included docker tool works slightly differently than it does if you’re working with that of the upstream project. This is intentional.

When we started the planning process for containers in RHEL 7.1, we had 3 goals in mind:

1. Give control over the search path to the end-user administrator
2. Enable a federated approach to search and discovery of docker-formatted container images
3. Support the ability for Red Hat customers to consume container images and other content included as part of their Red Hat Subscription

The changes we implemented, which are documented on the Red Hat Customer Portal, affect three different areas of the tool:

1. Additional registries for search and pull

The new  '--add-registry' option adds an additional registry to the list used when searching for an image. This allows the local administrator to expand “docker search” to include private and corporate registries. Search will query all registries on the list in parallel; the order does not matter here.

The same list is also used for “docker pull” of short-names. A short-name is an image name without an explicit registry, for example “docker pull rhel”. When working with short-names the order becomes very important.

How pull works across multiple registries

Red Hat recommends using fully qualified image names; this is especially important in Dockerfile FROM statements in an enterprise setting. A fully qualified image name (FQIN) can be made up of 3 parts:

[registry_hostname[:port]/][user_name/](repository_name:version_tag)

It is common that users will use image short-names for convenience. When pulling a short-name, the tool iterates over the list of configured registries and expands short-names locally for each of the configured registries. It then tries to pull the image registry by registry, until it finds a match. In this case, order matters as it starts with the first entry and then pulls from the next, with docker.io being the last. What gets pulled is always the expanded, fully qualified name.

The Red Hat default config in '/etc/sysconfic/docker' adds 'registry.access.redhat.com', which is the authoritative source for official Red Hat content. The default docker.io search path is hardcoded and remains enabled.

2) Representation of search results and fully qualified image names

The output of 'docker search' in Red Hat Enterprise Linux always lists the fully qualified image name. This is consistent with the recommendations to always use fully qualified names. It also avoids any ambiguity about the namespace in a federated model and can be especially useful when multiple private registries are used in an organization. Search results are aggregated in a single list, grouped by registry. The default sort is by star-count, then alphabetically.

In addition, it explicitly adds the name of the registry index in which the image was found. For example, Red Hat partners can choose to list certified content in the Red Hat catalog without limiting their options for distributing the content through their own registry.

3) Ability to block registries

Some organizations have strict policies on what content can and cannot be consumed when building applications, and many customers have asked for a way to control container image consumption to help them comply with regulations. The new  '--block-registry'  options allows an admin to blacklist a registry. This affects the search, resolution of short-names, and pulling of fully qualified names.

To establish Enterprise-level content control, an organization might use ‘--add-registry’ and '--block-registry' together in this way: limit access to private registries only by explicitly adding '--add-registry' and '--block-registry *' in  /etc/sysconfig/docker.

In addition, the Red Hat Enterprise Linux docker tool will also ask the user for confirmation before pushing an image to the public registry in order to avoid accidentally publishing private content.

Red Hat continues to work within the upstream Docker community to make this behavior part of the mainline.

Pulling it all together

The first thing I do is make sure that I’m running the latest version. The current version of the RHEL package at the time of this posting is docker-1.5.0-28.el7. To get the latest, run 'yum update' (RHEL) or 'atomic host upgrade' (Atomic). Note that while the Red Hat images are fully supported, these changes to the tool are still experimental and we expect that behavior will change over time as the upstream project evolves.

With the default config in Red Hat Enterprise Linux 7.1, a search for the rhel-tools container looks like this:

# docker search rhel-tools
NAME                                                         DESCRIPTION                                     STARS     OFFICIAL      AUTOMATED
redhat.com: registry.access.redhat.com/rhel7/rhel-tools   Provides the core systems administrator an...   0

Let's pull the rhel-tools image falling for the bad habit of short-names:

# docker pull rhel7/rhel-tools
Trying to pull repository registry.access.redhat.com/rhel7/rhel-tools ...
9a8ad4567c27: Pulling image (latest) from registry.access.redhat.com/rhel7/rhel-tools
9a8ad4567c27: Pulling image (latest) from registry.access.redhat.com/rhel7/rhel-tools, endpoint: https://registry.access.redhat.com/v1/
9a8ad4567c27: Pulling dependent layers
9a8ad4567c27: Pulling metadata
9a8ad4567c27: Pulling fs layer
9a8ad4567c27: Download complete
9a8ad4567c27: Download complete
Status: Downloaded newer image for registry.access.redhat.com/rhel7/rhel-tools:latest

Note that the image that was pulled has the fully qualified tag:

# docker images | grep "rhel7\/rhel-tools"
registry.access.redhat.com/rhel7/rhel-tools                        latest              9a8ad4567c27        7 weeks ago         994.8 MB
registry.access.redhat.com/rhel7/rhel-tools                        7.1-9               9a8ad4567c27        7 weeks ago         994.8 MB

This is pretty straight forward. Red Hat customers can directly consume Red Hat container images and control how content is accessed in an enterprise environment.

A hypothetical search for a Red Hat certified ISV image 'fancydb' would give the following result:

# docker search fancydb
NAME                                                                   DESCRIPTION                   STARS OFFICIAL AUTOMATED
redhat.com: registry-fancycorp.rhcloud.com/fancydb-rhel7/fancydb       Really fancy database app...  0 
redhat.com: registry-fancycorp.rhcloud.com/fancydb-rhel7/fancydb-tools Tools for ther really fan.... 0

As ISVs certify and list their applications in the Red Hat ISV catalog on access.redhat.com, customers will be able to directly pull software via the command line.

Now if we want to get some fedora community content, we might do:

# docker search fedora/nginx

NAME                                           DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED
docker.io: docker.io/fedora/nginx                                                              18                   [OK]
docker.io: docker.io/dasrick/fedora-nginx      NGINX image - port 80, 443 - based on Fedo...   0                    [OK]
docker.io: docker.io/parf/fedora-nginx-php     SSH, NGINX, PHP-FPM, SUPERVISORD                0                    
docker.io: docker.io/parf/nginx-php-fedora21   fedora21 + mainline(nginx) + php(remi)          0

Note that the interaction with docker.io has not changed, other than that the search results explicitly list the index. You’ll see that the index name is by default truncated; you can change this to the full hostname by using the '--no-trunc' option.

Suppose I want to include my own private registry. I can do this by changing the ADD_REGISTRY line in  '/etc/sysconfig/docker' to ADD_REGISTRY='--add-registry registry.access.redhat.com --add-registry myreg.mynet.net:5000'. Because I am lazy, I will also set INSECURE_REGISTRY='--insecure-registry myreg.mynet.net:5000'

We strongly recommend that you set proper certificates to protect the connections instead of doing the above.

Now, I'll do a docker search for a squid image that I built and pushed to my private registry:

# docker search squid
NAME                                                              DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED
docker.io: docker.io/jpetazzo/squid-in-a-can                                                                      10                   [OK]
docker.io: docker.io/sameersbn/squid                                                                              7                    [OK]
docker.io: docker.io/pmoust/squid-deb-proxy                       squid-deb-proxy provides an easy wrapper o...   2                    [OK]
[...]
myreg.mynet.net:5000/rhel7/squid-rhel7                                                                          0

What if I get confused and accidentally try to push my private squid-rhel7 image to the public registry? This is a bad idea because it would leak some internal network configs *and* violate my Red Hat Enterprise Linux Subscription agreement:

# docker tag d2d185c7bd43 docker.io/llunved/squid-rhel7
# docker push docker.io/llunved/squid-rhel7
Do you really want to push to public registry? [Y/n]: n
Nothing pushed.

Puh! It’s a good thing that it asked!

Next, we'll tighten things up a bit to ensure we don't use any public registries. Adding to /etc/sysconfig/docker:

BLOCK_REGISTRY='--block-registry *'

I can still see my own registry (the one that I added above):

# docker search squid
NAME                                                               DESCRIPTION                                     STARS     OFFICIAL    AUTOMATED
myreg.mynet.net:5000/rhel7/squid-rhel7                                                                          0

And I kept the Red Hat registry for RHEL content:

# docker search rhel

NAME                                                      DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED
redhat.com: registry.access.redhat.com/rhel6/rhel         This platform image provides a minimal run...   0                    
[...]
redhat.com: registry.access.redhat.com/rhel7/rhel         This platform image provides a minimal run...   0                    
redhat.com: registry.access.redhat.com/rhel7/rhel-tools   Provides the core systems administrator an...   0                    
redhat.com: registry.access.redhat.com/rhel7/rsyslog      A containerized version of the rsyslog uti...   0                    
redhat.com: registry.access.redhat.com/rhel7/sadc         A containerized version of the sysstat dat...   0

But I am limited to the registries I really want:

# docker pull registry.rootkit-centr.al/hackme
FATA[0000] Error: Blocked registry "registry.rootkit-centr.al"

And of course the admin could also turn off access to the Red Hat registry by removing registry.access.redhat.com from the ADD_REGISTRY line in '/etc/sysconfig/docker'.

Now this feature really becomes useful once I use a controlled local mirror registry... but we’ll save that for another blog post.

I’ve talked with a lot of customers, and they’re very excited about these new features. With them, local admins get control over the search path, including the ability to block access to unsanctioned sources. They can specify and prioritize the pull order of multiple registries.  And they get direct access to Red Hat certified container images as part of their Red Hat Enterprise Linux subscription. It’s a beautiful thing.