Migrating your base Image from CentOS to UBI

I’ve done a number of workshops of late where partners are moving to the Red Hat Universal Base Image (UBI) from CentOS for their base image. This post summarizes some easy steps to do it.

When we first started the certification program we required that all images certified needed to be built with a base image of Red Hat Enterprise Linux (RHEL) and the images needed to be hosted within our internal registry. This proved to be a pain point for a lot of partners going through the certification process.

We introduced UBI to help make that transition easier. Essentially, UBI is a stripped down version of RHEL base images. 

This subset of content is intended to enable customers, partners, and community members wishing to standardize on enterprise-grade Container Images (often referred to as a Base Images) for all of their containerized applications. These images are freely redistributable so that anyone can deploy onto Red Hat or non-Red Hat platforms.

UBI images are OCI-compliant container base operating system images with a number of  runtime languages and packages that are freely redistributable. UBI images can be obtained from theRed Hat container catalog. UBI images provide the same quality trusted foundation 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.

Converting your base image to use UBI can be a little tricky depending on what base image you currently use. For the purposes of this post we will be comparing CentOS to UBI and showing how easy it is to convert an image using CentOS to use UBI. 

Adding packages from the UBI repos only requires a few steps. Add the following layer to your Dockerfile for the container image. You will need to disable the subscription-manager plugin.

RUN yum install -y --disableplugin=subscription-manager package-name

If you need to install a package from the RHEL Server repository (this is enabled by default) add the following layer to your Dockerfile for the container image:

RUN yum install -y package-name

If you need to istall a package from the RHEL repository other than a UBI or RHEL Server, you will need to enable it manually. Add the following layer to your Dockerfile for the container image. 

RUN yum install -y --enablerepo=repository-name package-name

The /etc/yum.repos.d/ubi.repo file inside each UBI container contains entries for available UBI repositories. Those set to enabled = 1 are currently enabled. Refer to the baseurl for each repository to see the location of those packages. Type yum repolist to see the list of enabled repositories (yum is not available in the minimal UBI images). See "Add software to a running UBI container" if you need a refresher on this.

Converting an image from a CentOS base image to a UBI base image should be a relatively easy task. It is worth noting that when converting any image to UBI that services may work differently. In the following example we will take a simple Dockerfile and convert it from CentOS to UBI.

Converting to UBI

FROM centos:7
MAINTAINER The CentOS Project <cloud-ops@centos.org>
LABEL Vendor="CentOS" \
      License=GPLv2 \
      Version=2.4.6-40

RUN yum -y --setopt=tsflags=nodocs update && \
    yum -y --setopt=tsflags=nodocs install httpd && \
    yum clean all

EXPOSE 80

# Simple startup script to avoid some issues observed with container restart
ADD run-httpd.sh /run-httpd.sh
RUN chmod -v +x /run-httpd.sh

CMD ["/run-httpd.sh"]

CentOS 7 httpd Dockerfile

In this Dockerfile you can see that it uses CentOS 7, updates and installs httpd, and then cleans up after itself. From there it will expose port 80 and run a shell command that is included in the base directory of the project to run httpd. 

We will be achieving the same outcome with our UBI 8 image. The Dockerfile will be slightly different in the fact that we will include the command to run httpd as an additional layer rather than relying on a shell script to do the work for us. The services and commands may behave differently based on the new base OS so the actual commands will appear to be different. 
 

FROM registry.access.redhat.com/ubi8/ubi

# Required Atomic/OpenShift Labels - https://github.com/projectatomic/ContainerApplicationGenericLabels
LABEL name="ubi8-httpd" \
      vendor="Red Hat" \
      version="0.1.0" \
      release="1" \
      summary="UBI 8 Apache server" \
      description="Apache web server for UBI 8" \
      maintainer="rhc4tp"

# Update base image
RUN yum update --disablerepo=* --enablerepo=ubi-8-appstream --enablerepo=ubi-8-baseos -y && rm -rf /var/cache/yum

# Install httpd
RUN yum install --disablerepo=* --enablerepo=ubi-8-appstream --enablerepo=ubi-8-baseos httpd -y && rm -rf /var/cache/yum

# Add default Web page
RUN echo "The Web Server is Running" > /var/www/html/index.html

# Expose port
EXPOSE 80

# Start the service
CMD ["-D", "FOREGROUND"]
ENTRYPOINT ["/usr/sbin/httpd"]

# Always include a software license in the default location
# Required for Red Hat OpenShift certification
COPY licenses/ /licenses

UBI 8 httpd Dockerfile

In this UBI 8 Dockerfile for httpd, we added a few additional labels and included a licenses directory as well. These are prerequisites for Red Hat OpenShift Certification. Both have a command to make sure the base image is up to date, but we also included a verification command (echo “The Web Server is Running”). As you can see the services behave slightly differently.

You can now try building this container image to confirm its working correctly.

Build Image

$ sudo buildah bud -t nhartman/webserver .
$ sudo buildah images

Now that the container is built successfully, you can run the container. 

$ sudo podman run -d -p 80:80 nhartman/webserver
$ sudo podman ps

Image

Once the container is running try to verify HTTP Server is working properly. 

$ curl http://localhost/index.html
 

Image

In conclusion switching from CentOS to UBI can be a relatively painless process. Once you have successfully converted your image to use UBI you may want to consider certifying it to run on Red Hat OpenShift. 

For more information on Red Hat OpenShift Certification please take a look at our General Program Guide for Partners