Technical resources

Migrating your base Image from CentOS to UBI

August 19, 2020
4 minute read

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


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

CMD ["/"]


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.   


# Required Atomic/OpenShift Labels - 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

run the container


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

$ curl http://localhost/index.html  

Local host running


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


Neal Hartman avatar
Neal Hartman
Associate Software Engineer, Red Hat
Neal Hartman is an Associate Software Engineer for the Red Hat Certified Technology Ecosystem team. He supports Red Hat technology partners through their product certification journey specializing in the Red Hat OpenShift Operator certification offering. Neal joined the team in 2019 and lives in Raleigh, North Carolina with his wonderful wife and their three "fur-children".
Red Hat Partner Connect logo LinkedIn YouTube Facebook Twitter

Red Hat Products

Tools & Resources


About Red Hat Partner Connect

The Red Hat partner ecosystem is a catalyst for open innovation. It connects partners with a thriving network of companies, expertise, and opportunity. With Red Hat, there are multiple paths to partnership and the flexibility to adapt as your business needs change. We work to help you achieve financial success on your terms.

About Red Hat

We’re the world’s leading provider of enterprise open source solutions—including Linux, cloud, container, and Kubernetes. We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.