Chapter 4. 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. For RHEL 8, all Red Hat base images are available as new Universal Base Images (UBI). These include versions of RHEL standard, minimal, init, and Red Hat Software Collections that are all now freely available and redistributable. 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) for RHEL 8 provide the same quality RHEL software for building container images as their non-UBI predecessors (rhel6, rhel7, rhel-init, and rhel-minimal base images), but offer more freedom in how they are used and distributed.

Note

For a list of available Red Hat UBI images, and associated information about UBI repositories and source code, see Universal Base Images (UBI): Images, repositories, and packages.

4.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 8, there are standard, minimal and init base image available. Red Hat also provides a set of language runtime images, based on Application Streams, that you can build on when you are creating containers for applications that require specific runtimes. Runtime images include python, php, ruby, nodejs, and others. All of the RHEL 8 images are UBI images, which means that you can freely obtain and redistribute them.

There is a set of RHEL 7 images as well that you can run on RHEL 8 systems. For RHEL 7, there are both UBI (redistributable) and non-UBI (require subscription access and are non-redistributable) base images. Those images include three regular base images (rhel7, rhel-init, and rhel-minimal) and three UBI images (ubi7, ubi7-init, and ubi7-minimal).

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.

4.1.1. Using standard Red Hat base images

Standard RHEL 8 base images (ubi8) 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. 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). 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 tar, dmidecode, gzip, getfacl (and other acl commands), dmsetup (and other device mapper commands), and others.

4.1.2. Using minimal Red Hat base images

The ubi8-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 92M on disk and 32M 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. 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.
  • Modules for microdnf are not supported: Modules used with the dnf command let you install multiple versions of the same software, when available. The microdnf utility included with minimal images does not support modules. So if modules are required, you should use a non-minimal base images, which include yum.

If your goal, however, 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.

Red Hat intends for you to always use the latest version of the minimal images, which is implied by simply requesting ubi8/ubi-minimal or ubi8-minimal. Red Hat does not expect to support older versions of minimal images going forward.

4.1.3. Using Init Red Hat base images

The UBI ubi8-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.

Note

Because the ubi8-init image builds on top of the ubi8 image, their contents are mostly the same. There are a few critical differences, however. In ubi8-init, the Cmd is set to /sbin/init, instead of bash, to start the systemd Init service by default. It includes ps and process related commands (procps-ng package), which ubi8 does not. Also, ubi8-init sets SIGRTMIN+3 as the StopSignal, as systemd in ubi8-init ignores normal signals to exit (SIGTERM and SIGKILL), but will terminate if it receives SIGRTMIN+3.

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.

4.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 runtime images: Besides the three types of base images, UBI versions of various runtime images are available as well. These runtime 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 8 UBI image:

    • The ubi-8-baseos repo holds the redistributable subset of RHEL packages you can include in your container.
    • The ubi-8-appstream 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.
  • 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 7 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 RHEL 8 UBI images.

4.3. Get UBI images

The following table shows the UBI base images currently available. Notice that some of those images have multiple names you can use to refer to them.

Table 4.1. Available Red Hat Universal Base Images

Registry namesNamespaceImageRHEL version

registry.access.redhat.com

registry.redhat.io

/

ubi8

8.0.0

  

ubi8-minimal

8.0.0

  

ubi8-init

8.0.0

registry.access.redhat.com

registry.redhat.io

ubi8/

ubi

8.0.0

  

ubi-init

8.0.0

  

ubi-minimal

8.0.0

  

s2i-core

8.0.0

  

s2i-base

8.0.0

  

dotnet-21-runtime

8.0.0

  

dotnet-21

8.0.0

  

perl-526

8.0.0

  

php-72

8.0.0

  

nodejs-10

8.0.0

  

ruby-25

8.0.0

  

python-27

8.0.0

  

python-36

8.0.0

registry.redhat.io

rhel8

s2i-core

8.0.0

  

s2i-base

8.0.0

  

dotnet-21-runtime

8.0.0

  

dotnet-21

8.0.0

  

nginx-114

8.0.0

  

perl-526

8.0.0

  

php-72

8.0.0

  

nodejs-10

8.0.0

  

httpd-24

8.0.0

  

redis-5

8.0.0

  

varnish-6

8.0.0

  

ruby-25

8.0.0

  

python-27

8.0.0

  

python-36

8.0.0

  

memcached

8.0.0

  

net-snmp

8.0.0

  

sssd

8.0.0

  

ipa-server

8.0.0

  

support-tools

8.0.0

  

rsyslog

8.0.0

  

GCC

8.0.0

  

rust-toolset

8.0.0

  

go-toolset

8.0.0

  

llvm-toolset

8.0.0

  

postgresql-10

8.0.0

  

postgresql-96

8.0.0

  

mysql-80

8.0.0

  

mariadb-103

8.0.0

registry.access.redhat.com

registry.redhat.io

/

ubi7

7.6.4

  

ubi7-minimal

7.6.4

  

ubi7-init

7.6.4

registry.access.redhat.com

registry.redhat.io

ubi7/

ubi

7.6.4

  

ubi-init

7.6.4

  

ubi-minimal

7.6.4

  

php-72

7.6.4

  

nodejs-8

7.6.4

  

ruby-25

7.6.4

  

python-27

7.6.4

  

python-36

7.6.4

  

s2i-core

7.6.4

  

s2i-base

7.6.4

4.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/ubi8/ubi:latest
# podman pull registry.access.redhat.com/ubi8/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/ubi8/ubi-minimal  latest  c94a444803e3  8 hours ago  80.9 MB
registry.access.redhat.com/ubi8/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.

4.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/ubi8/ubi
# podman tag registry.access.redhat.com/ubi8/ubi registry.example.com:5000/ubi8/ubi
# podman push registry.example.com:5000/ubi8/ubi

While there are few restrictions on how you use these images, there are some restrictions about how you can refer to them. For example, you can’t call those images 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.

4.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/ubi8/ubi-minimal:latest /bin/bash
[root@da9213157c51 /]#
# podman run --rm -it registry.access.redhat.com/ubi8/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 the ubi-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.

4.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 that 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, the microdnf command (with a smaller feature set) is included instead of yum.

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.

4.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.

4.7.2. Adding software inside the standard UBI container

To ensure the containers you build can be redistributed, disable non-UBI yum repositories in the standard UBI image when you add software. If you disable all yum repositories except for UBI repositories, only packages from the freely available repos are used when you add software.

With a shell open inside a standard UBI base image container (ubi8/ubi) from a subscribed RHEL host, run the following command to add a package to that container (for example, the bzip2 package):

# yum install --disablerepo=* --enablerepo=ubi-8-appstream --enablerepo=ubi-8-baseos bzip2

To add software inside a standard UBI container that is in the RHEL server repo, but not in UBI repos, don’t disable any repositories 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
Warning

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.

4.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
Warning

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.

4.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 any yum repositories. For example:

# yum install bzip2

To install that package on an unsubscribed 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.

4.7.5. 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 all non-UBI yum repositories 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:

Note

For ubi8/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
  1. Create a Dockerfile: Add a Dockerfile with the following contents to a new directory:

    FROM registry.access.redhat.com/ubi8/ubi
    USER root
    LABEL maintainer="John Doe"
    # Update image
    RUN yum update --disablerepo=* --enablerepo=ubi-8-appstream --enablerepo=ubi-8-baseos -y && rm -rf /var/cache/yum
    RUN yum install --disablerepo=* --enablerepo=ubi-8-appstream --enablerepo=ubi-8-baseos 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"]
  2. 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/ubi8/ubi:latest
    STEP 2: USER root
    STEP 3: LABEL maintainer="John Doe"
    STEP 4: RUN yum update --disablerepo=* --enablerepo=ubi-8-appstream --enablerepo=ubi-8-baseos -y
    . . .
    No packages marked for update
    STEP 5: RUN yum install --disablerepo=* --enablerepo=ubi-8-appstream --enablerepo=ubi-8-baseos 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.37-10
                                                  latest-rhubi-8.0-appstream 1.4 M
    Installing dependencies:
     apr                x86_64 1.6.3-9.el8        latest-rhubi-8.0-appstream 125 k
     apr-util           x86_64 1.6.1-6.el8        latest-rhubi-8.0-appstream 105 k
     httpd-filesystem   noarch 2.4.37-10
                                                  latest-rhubi-8.0-appstream  34 k
     httpd-tools        x86_64 2.4.37-10.
    ...
    
    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
  3. 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

4.7.6. Using AppStream runtime images

Red Hat Enterprise Linux 8 AppStream 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 most 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 a few examples of AppStream container images built on UBI base images, that are available from the Red Hat Registry (registry.access.redhat.com or registry.redhat.io):

  • ubi8/php-72: PHP 7.2 platform for building and running applications
  • ubi8/nodejs-10: Node.js 10 platform for building and running applications. Used by Node.js 10 Source-To-Image builds
  • ubi8/ruby25: Ruby 2.5 platform for building and running applications
  • ubi8/python-27: Python 2.7 platform for building and running applications
  • ubi8/python-36: Python 3.6 platform for building and running applications
  • ubi8/s2i-core: Base image with essential libraries and tools used as a base for builder images like perl, python, ruby, and so on
  • ubi8/s2i-base: Base image for Source-to-Image builds

Because these UBI images contain 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.

RHEL 8 AppStream container images are updated every time RHEL 8 base images are updated. For RHEL 7, these same images (referred to as Red Hat Software Collections images) are updated on a schedule that is separate from RHEL base image updates (as are related images for Dotnet and DevTools). 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.

4.7.7. 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:

# yum install yum-utils -y
# 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.

4.7.8. 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 (ubi8/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, type podman 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.

4.7.9. 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

4.7.10. 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