Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 10. Using Red Hat subscriptions in builds

Use the following sections to run entitled builds on OpenShift Container Platform.

To use Red Hat subscriptions within a build, you should create an ImageStream to reference the universal base image (UBI).

Builds that reference the UBI directly from registry.redhat.io will require a pull secret.

Prerequisites

  • You must create a pull secret for registry.redhat.io, and link it to a user project.

Procedure

  • To create an imagestreamtag in a single project: 

    $ oc tag --source=docker registry.redhat.io/ubi7/ubi:latest ubi:latest
    Copy to Clipboard Toggle word wrap

  • To create an imagestreamtag in the OpenShift Container Platform namespace, making it available to developers in all projects: 

    $ oc tag --source=docker registry.redhat.io/ubi7/ubi:latest ubi:latest -n openshift
    Copy to Clipboard Toggle word wrap

Builds that use Red Hat subscriptions to install content must include the entitlement keys as a build secret.

Prerequisites

You must have access to Red Hat entitlements through your subscription, and the entitlements must have separate public and private key files.

Procedure

  1. Create a secret containing your entitlements, ensuring that there are separate files containing the public and private keys: 

    $  oc create secret generic etc-pki-entitlement --from-file /path/to/entitlement/{ID}.pem \
> --from-file /path/to/entitlement/{ID}-key.pem ...
    Copy to Clipboard Toggle word wrap

  2. Add the secret as a build input in the build configuration: 

    source:
  secrets:
  - secret:
      name: etc-pki-entitlement
    destinationDir: etc-pki-entitlement
    Copy to Clipboard Toggle word wrap

There are two paths to pulling in the base RHEL image:

  • Add the pull secret to registry.redhat.io to your project.
  • Create an imagestream in the openshift namespace for the RHEL-based image. This makes the imagestream available across the cluster.

10.3. Running builds with Subscription Manager
Copy link

Builds that use the Subscription Manager to install content must provide appropriate configuration files and certificate authorities for subscribed repositories.

Prerequisites

You must have access to the Subscription Manager’s configuration and certificate authority files.

Procedure

  1. Create a ConfigMap for the Subscription Manager configuration: 

    $ oc create configmap rhsm-conf --from-file /path/to/rhsm/rhsm.conf
    Copy to Clipboard Toggle word wrap

  2. Create a ConfigMap for the certificate authority: 

    $ oc create configmap rhsm-ca --from-file /path/to/rhsm/ca/redhat-uep.pem
    Copy to Clipboard Toggle word wrap

  3. Add the Subscription Manager configuration and certificate authority to the BuildConfig: 

    source:
    configMaps:
    - configMap:
        name: rhsm-conf
      destinationDir: rhsm-conf
    - configMap:
        name: rhsm-ca
      destinationDir: rhsm-ca
    Copy to Clipboard Toggle word wrap

10.3.2. Docker builds using Subscription Manager
Copy link

Docker strategy builds can use the Subscription Manager to install subscription content.

Prerequisites

The entitlement keys, subscription manager configuration, and subscription manager certificate authority must be added as build inputs.

Procedure

Use the following as an example Dockerfile to install content with the Subscription Manager: 

FROM registry.redhat.io/rhel7:latest
USER root
# Copy entitlements
COPY ./etc-pki-entitlement /etc/pki/entitlement
# Copy subscription manager configurations
COPY ./rhsm-conf /etc/rhsm
COPY ./rhsm-ca /etc/rhsm/ca
# Delete /etc/rhsm-host to use entitlements from the build container
RUN rm /etc/rhsm-host && \
    # Initialize /etc/yum.repos.d/redhat.repo
    # See https://access.redhat.com/solutions/1443553
    yum repolist --disablerepo=* && \
    subscription-manager repos --enable <enabled-repo> && \
    yum -y update && \
    yum -y install <rpms> && \
    # Remove entitlements and Subscription Manager configs
    rm -rf /etc/pki/entitlement && \
    rm -rf /etc/rhsm
# OpenShift requires images to run as non-root by default
USER 1001
ENTRYPOINT ["/bin/bash"]
Copy to Clipboard Toggle word wrap

10.4. Running builds with Satellite subscriptions
Copy link

10.4.1. Adding Satellite configurations to builds
Copy link

Builds which use Satellite to install content must provide appropriate configurations to obtain content from Satellite repositories.

Prerequisites

  • You must provide or create a yum-compatible repository configuration file that downloads content from your Satellite instance.

    Sample repository configuration

    [test-<name>]
 name=test-<number>
 baseurl = https://satellite.../content/dist/rhel/server/7/7Server/x86_64/os
 enabled=1
 gpgcheck=0
 sslverify=0
 sslclientkey = /etc/pki/entitlement/...-key.pem
 sslclientcert = /etc/pki/entitlement/....pem
    Copy to Clipboard Toggle word wrap

Procedure

  1. Create a ConfigMap containing the Satellite repository configuration file: 

    $ oc create configmap yum-repos-d --from-file /path/to/satellite.repo
    Copy to Clipboard Toggle word wrap

  2. Add the Satellite repository configuration to the BuildConfig: 

    source:
    configMaps:
    - configMap:
        name: yum-repos-d
      destinationDir: yum.repos.d
    Copy to Clipboard Toggle word wrap

Docker strategy builds can use Satellite repositories to install subscription content.

Prerequisites

The entitlement keys and Satellite repository configurations must be added as build inputs.

Procedure

Use the following as an example Dockerfile to install content with Satellite: 

FROM registry.redhat.io/rhel7:latest
USER root
# Copy entitlements
COPY ./etc-pki-entitlement /etc/pki/entitlement
# Copy repository configuration
COPY ./yum.repos.d /etc/yum.repos.d
# Delete /etc/rhsm-host to use entitlements from the build container
RUN rm /etc/rhsm-host && \
    # yum repository info provided by Satellite
    yum -y update && \
    yum -y install <rpms> && \
    # Remove entitlements
    rm -rf /etc/pki/entitlement
# OpenShift requires images to run as non-root by default
USER 1001
ENTRYPOINT ["/bin/bash"]
Copy to Clipboard Toggle word wrap

10.5. Squash layers with docker builds
Copy link

Docker builds normally create a layer representing each instruction in a Dockerfile. Setting the imageOptimizationPolicy to SkipLayers will merge all instructions into a single layer on top of the base image.

Procedure

  • Set the imageOptimizationPolicy to SkipLayers: 
strategy:
  dockerStrategy:
    imageOptimizationPolicy: SkipLayers
Copy to Clipboard Toggle word wrap

10.6. Additional resources
Copy link

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat