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:
- Give control over the search path to the end-user administrator
- Enable a federated approach to search and discovery of docker-formatted container images
- 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:
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:
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 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.