Chapter 2. Using Red Hat Universal Base Images (standard, minimal, and runtimes)
Red Hat Enterprise Linux (RHEL) base images are meant to form the foundation for the container images you build. As of April 2019, new Universal Base Image (UBI) versions of RHEL standard, minimal, init, and Red Hat Software Collections images are available that add to those images the ability to be freely redistributed. Characteristics of RHEL base images include:
- Supported: Supported by Red Hat for use with your containerized applications. Contains the same secured, tested, and certified software packages you have in Red Hat Enterprise Linux.
- Cataloged: Listed in the Red Hat Container Catalog, where you can find descriptions, technical details, and a health index for each image.
- Updated: Offered with a well-defined update schedule, so you know you are getting the latest software (see Red Hat Container Image Updates).
- Tracked: Tracked by errata, to help you understand the changes that go into each update.
- Reusable: Only need to be downloaded and cached in your production environment once, where each base image can be reused by all containers that include it as their foundation.
Red Hat Universal Base Images (UBI) provide the same quality RHEL software for building container images as their predecessors (rhel6
, rhel7
, rhel-init
, and rhel-minimal
base images), but offer more freedom in how they are used and distributed.
2.1. What are Red Hat base images?
Red Hat provides multiple base images that you can use as a starting point for your own images. These images are available through the Red Hat Registry (registry.access.redhat.com and registry.redhat.io) and described in the Red Hat Container Catalog.
For RHEL 7, there are two different versions of each standard, minimal and init base image available. Red Hat also provides a set of Red Hat Software Collections images that you can build on when you are creating containers for applications that require specific runtimes. These include python, php, nodejs, and others.
Although Red Hat does not offer tools for running containers on RHEL 6 systems, it does offer RHEL 6 container images you can use. There are standard (rhel6
) and Init (rhel6-init
) base image available for RHEL 6, but no minimal RHEL 6 image. Likewise, there are no RHEL 6 UBI images.
2.1.1. Using standard Red Hat base images
There is a legacy rhel7/rhel
image and a UBI ubi7
image on which you can add your own software or additional RHEL 7 software. The contents are nearly identical, with the main differences that the former requires a RHEL paid subscription and the two images draw from different image registries and yum repositories.
Standard RHEL base images have a robust set of software features that include the following:
-
init system: All the features of the systemd initialization system you need to manage systemd services are available in the standard base images. The
rhel6
base images include a minimalistic init system similar to System V. These init systems let you install RPM packages that are pre-configured to start up services automatically, such as a Web server (httpd) or FTP server (vsftpd). -
yum: Software needed to install software packages is included via the standard set of
yum
commands (yum
,yum-config-manager
,yumdownloader
, and so on). When a legacy standard base image is run on a RHEL system, you will be able to enable repositories and add packages as you do directly on a RHEL system, while using entitlements available on the host. For the UBI base images, you have access to free yum repositories for adding and updating software. -
utilities: The standard base image includes some useful utilities for working inside the container. Utilities that are in this base image that are not in the minimal images include
ps
,tar
,cpio
,dmidecode
,gzip
,lsmod
(and other module commands),getfacl
(and other acl commands),dmsetup
(and other device mapper commands), and others. - python: Python runtime libraries and modules (currently Python 2.7) are included in the standard base image. No python packages are included in the minimal base image.
2.1.2. Using minimal Red Hat base images
The legacy rhel7-minimal
(or rhel7-atomic
) and UBI ubi7-minimal
images are stripped-down RHEL images to use when a bare-bones base image in desired. If you are looking for the smallest possible base image to use as part of the larger Red Hat ecosystem, you can start with these minimal images.
RHEL minimal images provide a base for your own container images that is less than half the size of the standard image, while still being able to draw on RHEL software repositories and maintain any compliance requirements your software has.
Here are some features of the minimal base images:
- Small size: Minimal images are about 75M on disk and 28M compressed. This makes it less than half the size of the standard images.
- Software installation (microdnf): Instead of including the full-blown yum facility for working with software repositories and RPM software packages, the minimal images includes the microdnf utility. Microdnf is a scaled-down version of dnf. It includes only what is needed to enable and disable repositories, as well as install, remove, and update packages. It also has a clean option, to clean out cache after packages have been installed.
- Based on RHEL packaging: Because minimal images incorporate regular RHEL software RPM packages, with a few features removed such as extra language files or documentation, you can continue to rely on RHEL repositories for building your images. This allows you to still maintain compliance requirements you have that are based on RHEL software. Features of minimal images make them perfect for trying out applications you want to run with RHEL, while carrying the smallest possible amount of overhead.
If your goal is just to try to run some simple binaries or pre-packaged software that doesn’t have a lot of requirements from the operating system, the minimal images might suit your needs. If your application does have dependencies on other software from RHEL, you can simply use microdnf to install the needed packages at build time.
Here are some challenges related to using minimal images:
- Common utilities missing: What you don’t get with minimal images is an initialization and service management system (systemd or System V init), a Python run-time environment, and a bunch of common shell utilities. Although you can install that software later, installing a large set of software, such as systemd, might actually make the container larger than it would be if you were to just use the init container.
-
Older minimal images not supported: Red Hat intends for you to always use the latest version of the minimal images, which is implied by simply requesting
rhel-minimal
orubi7-minimal
. Red Hat does not expect to support older versions of minimal images going forward. -
Modules for microdnf are not supported: Modules used with the
dnf
command let you install multiple versions of the same software, when available. Themicrodnf
utility included with minimal images does not support modules. So if modules are required, you should use a non-minimal image (such as the standard or init UBI images, which both include yum).
2.1.3. Using Init Red Hat base images
The legacy rhel7-init
and UBI ubi7-init
images contains the systemd initialization system, making them useful for building images in which you want to run systemd services, such as a web server or file server. The Init image contents are less than what you get with the standard images, but more than what is in the minimal images.
Historically, Red Hat Enterprise Linux base container images were designed for Red Hat customers to run enterprise applications, but were not free to redistribute. This can create challenges for some organizations that need to redistribute their applications. That’s where the Red Hat Universal Base Images come in.
2.2. How are UBI images different?
UBI images were created so you can build your container images on a foundation of official Red Hat software that can be freely shared and deployed. From a technical perspective, they are nearly identical to legacy Red Hat Enterprise Linux images, which means they have great security, performance, and life cycles, but they are released under a different End User License Agreement. Here are some attributes of Red Hat UBI images:
- Built from a subset of RHEL content: Red Hat Universal Base images are built from a subset of normal Red Hat Enterprise Linux content. All of the content used to build selected UBI images is released in a publicly available set of yum repositories. This lets you install extra packages, as well as update any package in UBI base images.
- Redistributable: The intent of UBI images is to allow Red Hat customers, partners, ISVs, and others to standardize on one container base image, allowing users to focus on application needs instead of distribution rules. These images can be shared and run in any environment capable of running those images. As long as you follow some basic guidelines, you will be able to freely redistribute your UBI-based images.
- Base and RHSCL images: Besides the three types of base images, UBI versions of some Red Hat Software Collections (RHSCL) runtime images are available as well. These RHSCL images provide a foundation for applications that can benefit from standard, supported runtimes such as python, php, nodejs, and ruby.
Enabled yum repositories: The following yum repositories are enabled within each RHEL 7 UBI image:
-
The
ubi-7
repo holds the redistributable subset of RHEL packages you can include in your container. -
The
ubi-7-rhscl
repo holds Red Hat Software Collections packages that you can add to a UBI image to help you standardize the environments you use with applications that require particular runtimes. -
The
ubi-7-rhah
repo includes RHEL Atomic Host packages needed to manage subscriptions andmicrodnf
(the tinyyum
replacement used to install RPM packages on the minimal images). Note that some versions of ubi-minimal images do not have this repo enabled by default. -
The
ubi-7-optional
repo includes packages from the RHEL server optional repository.
-
The
- Licensing: You are free to use and redistribute UBI images, provided you adhere to the Red Hat Universal Base Image End User Licensing Agreement.
- Adding UBI RPMs: You can add RPM packages to UBI images from preconfigured UBI repositories. If you happen to be in a disconnected environment, you must whitelist the UBI Content Delivery Network (https://cdn-ubi.redhat.com) to use that feature. See the Connect to https://cdn-ubi.redhat.com solution for details.
Although the legacy RHEL base images will continue to be supported, UBI images are recommended going forward. For that reason, examples in the rest of this chapter are done with UBI images.
2.3. Get UBI images
To find the current set of available Red Hat UBI images, refer to Universal Base Images (UBI): Images, repositories, and packages or search the Red Hat Container Catalog.
2.4. Pull UBI images
To pull UBI images to your system so you can use them with tools such as podman, buildah or skopeo, type the following:
# podman pull registry.access.redhat.com/ubi7/ubi:latest # podman pull registry.access.redhat.com/ubi7/ubi-minimal:latest
To check that the images are available on your system, type:
# podman images REPOSITORY TAG IMAGE ID CREATED SIZE registry.access.redhat.com/ubi7/ubi-minimal latest c94a444803e3 8 hours ago 80.9 MB registry.access.redhat.com/ubi7/ubi latest 40b488f87628 17 hours ago 214 MB
When pulled in this way, images are available and usable by podman
, buildah
, skopeo
and the CRI-O container image, but they are not available to the Docker service or docker
command. To use these images with Docker, you can run docker pull
instead.
2.5. Redistributing UBI images
After you pull a UBI image, you are free to push it to your own registry and share it with others. You can upgrade or add to that image from UBI yum repositories as you like. Here is an example of how to push a UBI image to your own or another third-party repository:
# podman pull registry.redhat.io/ubi7/ubi # podman tag registry.access.redhat.com/ubi7/ubi registry.example.com:5000/ubi7/ubi # podman push registry.example.com:5000/ubi7/ubi
While there are few restrictions on how you use this image, there are some restrictions about how you can refer to it. For example, you can’t call that image 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.
2.6. Run UBI images
To start a container from a UBI image and run the bash shell in that image (so you can look around inside), do the following (type exit when you are done):
# podman run --rm -it registry.access.redhat.com/ubi7/ubi-minimal:latest /bin/bash [root@da9213157c51 /]# # podman run --rm -it registry.access.redhat.com/ubi7/ubi:latest /bin/bash bash-4.2#
While in the container:
-
Run
rpm -qa
to see a list of package inside each container. -
Type
yum list available
to see packages available to add to the image from the UBI yum repos. (The yum command is not available in theubi-minimal
containers.) - Get source code, as described in the "Getting UBI Container Image Source Code," later in this chapter.
On systems that include the Docker service, you can use docker run
instead.
2.7. Add software to a running UBI container
UBI images are built from 100% Red Hat content. These UBI images also provide a subset of Red Hat Enterprise Linux packages which are freely available to install for use with UBI. To add or update software, UBI images are pre-configured to point to the freely available yum repositories that hold official Red Hat RPMs.
To add packages from UBI repos to running UBI containers:
-
On
ubi
images, the yum command is installed to let you draw packages -
On
ubi-minimal
images, themicrodnf
command (with a smaller feature set) is included instead ofyum
.
Keep in mind that installing and working with software packages directly in running containers is just for adding packages temporarily or learning about the repos. Refer to the “Build a UBI-based image” for more permanent ways of building UBI-based images.
When you add software to a UBI container, procedures differ for updating UBI images on a subscribed RHEL host or on an unsubscribed (or non-RHEL) system. Those two ways of working with UBI images are illustrated below.
2.7.1. Adding software to a UBI container (subscribed host)
If you are running a UBI container on a registered and subscribed RHEL host, the main RHEL Server repository is enabled inside the standard UBI container, along with all the UBI repos. So the full set of Red Hat packages is available. From the UBI minimal container, All UBI repos are enabled by default, but no repos are enabled from the host by default.
2.7.2. Adding software inside the standard UBI container
To ensure the containers you build can be redistributed, disable subscription management in the standard UBI image when you add software. If you disable the subscription-manager plugin, only packages from the freely available repos are used when you add software.
With a shell open inside a standard UBI base image container (ubi7/ubi
) from a subscribed RHEL host, run the following command to add a package to that container (for example, the bzip2 package):
# yum install --disableplugin=subscription-manager bzip2
To add software inside a standard UBI container that is in the RHEL server repo, but not in UBI repos, leave the subscription-manager plugin intact and just install the package:
# yum install zsh
To install a package that is in a different host repo from inside the standard UBI container, you have to explicitly enable the repo you need. For example:
# yum install --enablerepo=rhel-7-server-optional-rpms zsh-html
Installing Red Hat packages that are not inside the Red Hat UBI repos might limit how widely you can distribute the container outside of subscribed hosts.
2.7.3. Adding software inside the minimal UBI container
UBI yum repositories are enabled inside the UBI minimal image by default.
To install the same package demonstrated earlier (bzip2) from one of those UBI yum repositories on a subscribed RHEL host from the UBI minimal container, type:
# microdnf install bzip2
To install packages inside a minimal UBI container from repos available on a subscribed host that are not part of a UBI yum repo, you would have to explicitly enable those repos. For example:
# microdnf install --enablerepo=rhel-7-server-rpms zsh # microdnf install --enablerepo=rhel-7-server-rpms \ --enablerepo=rhel-7-server-optional-rpms zsh-html
Using non-UBI RHEL repositories to install packages in your UBI images could restrict your ability to share those images to run outside of subscribed RHEL systems.
2.7.4. Adding software to a UBI container (unsubscribed host)
To add software packages to a running container that is either on an unsubscribed RHEL host or some other Linux system, you don’t have to disable the subscription-manager plugin. For example:
# yum install bzip2
To install that package on a subscribed RHEL host from the UBI minimal container, type:
# microdnf install bzip2
As noted earlier, both of these means of adding software to a running UBI container are not intended for creating permanent UBI-based container images. For that, you should build new layers on to UBI images, as described in the following section.
2.8. Build a UBI-based image
You can build UBI-based container images in the same way you build other images, with one exception. You should disable Red Hat subscriptions when you actually build the images, if you want to be sure that your image only contains Red Hat software that you can redistribute.
Here’s an example of creating a UBI-based Web server container from a Dockerfile with the buildah
utility:
For ubl7/ubi-minimal images, use microdnf instead of yum below:
RUN microdnf update -y && rm -rf /var/cache/yum RUN microdnf install httpd -y && microdnf clean all
Create a Dockerfile: Add a
Dockerfile
with the following contents to a new directory:FROM registry.access.redhat.com/ubi7/ubi USER root LABEL maintainer="John Doe" # Update image RUN yum update --disableplugin=subscription-manager -y && rm -rf /var/cache/yum RUN yum install --disableplugin=subscription-manager httpd -y && rm -rf /var/cache/yum # Add default Web page and expose port RUN echo "The Web Server is Running" > /var/www/html/index.html EXPOSE 80 # Start the service CMD ["-D", "FOREGROUND"] ENTRYPOINT ["/usr/sbin/httpd"]
Build the new image: While in that directory, use
buildah
to create a new UBI layered image:# buildah bud -t johndoe/webserver . STEP 1: FROM registry.access.redhat.com/ubi7/ubi:latest STEP 2: USER root STEP 3: MAINTAINER John Doe STEP 4: RUN yum update --disableplugin=subscription-manager -y . . . No packages marked for update STEP 5: RUN yum install --disableplugin=subscription-manager httpd -y Loaded plugins: ovl, product-id, search-disabled-repos Resolving Dependencies --> Running transaction check ============================================================= Package Arch Version Repository Size ============================================================= Installing: httpd x86_64 2.4.6-88.el7 ubi-7 1.2 M Installing for dependencies: apr x86_64 1.4.8-3.el7_4.1 ubi-7 103 k apr-util x86_64 1.5.2-6.el7 ubi-7 92 k httpd-tools x86_64 2.4.6-88.el7 ubi-7 90 k mailcap noarch 2.1.41-2.el7 ubi-7 31 k redhat-logos noarch 70.0.3-7.el7 ubi-7 13 M Transaction Summary ... Complete! STEP 6: RUN echo "The Web Server is Running" > /var/www/html/index.html STEP 7: EXPOSE 80 STEP 8: CMD ["-D", "FOREGROUND"] STEP 9: ENTRYPOINT ["/usr/sbin/httpd"] STEP 10: COMMIT ... Writing manifest to image destination Storing signatures --> 36a604cc0dd3657b46f8762d7ef69873f65e16343b54c63096e636c80f0d68c7
Test: Test the UBI layered webserver image:
# podman run -d -p 80:80 johndoe/webserver bbe98c71d18720d966e4567949888dc4fb86eec7d304e785d5177168a5965f64 # curl http://localhost/index.html The Web Server is Running
2.9. Using Red Hat Software Collections runtime images
Red Hat Software Collections offers another set of container images that you can use as the basis for your container builds. These images are built on RHEL standard base images, with some already updated as UBI images. Each of these images include additional software you might want to use for specific runtime environments.
So, if you expect to build multiple images that require, for example, php runtime software, you can use provide a more consistent platform for those images by starting with a PHP software collections image.
Here are examples of Red Hat Software Collections container images built on UBI base images, that are available from the Red Hat Registry (registry.access.redhat.com or registry.redhat.io):
- ubi7/php-72: PHP 7.2 platform for building and running applications
- ubi7/nodejs-8: Node.js 8 platform for building and running applications. Used by Node.js 8 Source-To-Image builds
- ubi7/ruby-25: Ruby 2.5 platform for building and running applications
- ubi7/python-27: Python 2.7 platform for building and running applications
- ubi7/python-36: Python 3.6 platform for building and running applications
- ubi7/s2i-core: Base image with essential libraries and tools used as a base for builder images like perl, python, ruby, and so on
- ubi7/s2i-base: Base image for Source-to-Image builds
Because these UBI images container the same basic software as their legacy image counterparts, you can learn about those images from the Using Red Hat Software Collections Container Images guide. Be sure to use the UBI image names to pull those images.
Red Hat Software Collections container images are updated every time RHEL base images are updated. Search the Red Hat Container Catalog for details on any of these images. For more information on update schedules, see Red Hat Container Image Updates.
2.10. Getting UBI Container Image Source Code
You can download the source code for all UBI base images (excluding the minimal images) by starting up those images with a bash shell and running the following set of commands from inside that container:
for i in `rpm -qa` do yumdownloader --source $i done
The source code RPM for each binary RPM package is downloaded to the current directory. Because the UBI minimal images include a subset of RPMs from the regular UBI images, running the yumdownloader
loop just shown will get you the minimal image packages as well.
2.11. Tips and tricks for using UBI images
Here are a few issues to consider when working with UBI images:
- Hundreds of RPM packages used in existing Red Hat Software Collections runtime images are stored in the yum repositories packaged with the new UBI images. Feel free to install those RPMs on your UBI images to emulate the runtime (python, php, nodejs, etc.) that interests you.
-
Because some language files and documentation have been stripped out of the minimal UBI image (
ubi7/ubi-minimal
), running rpm -Va inside that container will show the contents of many packages as being missing or modified. If having a complete list of files inside that container is important to you, consider using a tool such as Tripwire to record the files in the container and check it later. -
After a layered image has been created, use
podman history
to check which UBI image it was built on. For example, after completing the webserver example shown earlier, typepodman history johndoe/webserver
to see that the image it was built on includes the image ID of the UBI image you added on the FROM line of the Dockerfile.
2.12. How to request new features in UBI?
Red Hat partners and customers can request new features, including package requests, by filing a support ticket through standard methods. Non-Red Hat customers do not receive support, but can file requests through the standard Red Hat Bugzilla for the appropriate RHEL product. See also: Red Hat Bugzilla Queue
2.13. How to file a support case for UBI?
Red Hat partners and customers can file support tickets through standard methods when running UBI on a supported Red Hat platform (OpenShift/RHEL). Red Hat support staff will guide partners and customers
See also: Open a Support Case