Using Red Hat activation keys to access subscription content

Most Red Hat software requires a subscription to access. Activation keys are the preferred method for using Red Hat subscriptions with Konflux builds and are supported by the all types of container builds, including hermetic builds using the prefetch-dependencies task.

Previously, mounting entitlement certificates directly as secrets was advocated but this is discouraged by Red Hat since those certificates are intended to be regularly revoked and refreshed by the subscription-manager system. Direct use of entitlement certificates is still supported by Konflux but discouraged. Entitlement certificate docs are here.

To learn how to create an activation keys see the Red Hat documentation.

When your activation key is created, you will need to create a secret with two values: your "org id" and the name of your activation key.

Adding activation keys to the workspace

You will need to create one or more secrets in your Konflux namespace (one per activation key). First, decide what to name the secrets and the scope they should have. You can control the scope of the activation key you add with the name.

Adding subscription entitlement for an entire workspace

Both the buildah and prefetch-dependencies tasks accept an activation key with a default name of activation-key. If you use this name for your secret, all of the builds in your workspace will automatically use the activation key.

Adding subscription entitlement for a specific component build

Sometimes, you only want certain builds to have the activation key, particularly when you need to have more than one key with different repository configurations in the same workspace. To do this, choose a different name for your activation key secret (not activation-key). Then, add a parameter to your component’s pipeline yaml:

- name: ACTIVATION_KEY
  value: my-secret-name

Create the activation key secrets

Create activation key secret through the UI

  1. Access the Secrets section in the konflux UI and click on Add secret.

  2. Set the secret name to activation-key.

  3. Add the first key with the name org and and set the value to your org id.

  4. Add a second key with the name activationkey and set the value to the name of your activation key.

  5. Save the secret by clicking Add secret

Create activation key secret through console

Alternatively, you can create the secret through the CLI. After logging into your cluster and navigating to your namespace, run the following command:

kubectl create secret generic activation-key -n <your-tenant> --from-literal=org=<your org id> --from-literal=activationkey=<your activation key name>

Using subscription content in a build

Non-hermetic (network connected) builds:

Automatic registration

The buildah task will use a provided activation key to register itself with Red Hat subscription manager and mount the necessary certificates to the build environment. Simply add dnf or yum install commands to your Containerfile.

If your activation key includes more than the default repositories, add the following command inside your Containerfile in order update repository metadata: 
subscription-manager refresh

Explicit registration

If you include a subscription-manager register command in your Containerfile, automatic registration will be disabled. You can control subscription-manager directly using the normal commands.

Hermetic (network isolated) builds:

The prefetch-dependencies task can use an activation key to register and fetch RPMs. All repositories configured for the activation key will be enabled for prefetch. If the default name was used for the secret (activation-key) no configuration is necessary. Otherwise, provide the ACTIVATION_KEY parameter to the build pipeline as noted above.

Configuring an RPM lockfile for hermetic builds

The rpm-lockfile-prototype tool uses live dnf metadata to resolve a given rpms.in.yaml file into an rpms.lock.yaml file in which every RPM is pinned to a repository and version. Because it uses live metadata, the configuration of package repositories on the system will influence the results.

Let’s explore a simple scenario that should illustrate all pertinent parts of the process.

We will create a lockfile that includes the openshift-clients RPM which:

  • requires a subscription to the OpenShift product

  • is not located in the default Red Hat Enterprise Linux repositories

  • is available for multiple architectures

This RPM is available in the following repositories:

architecture

repository

x86_64

rhocp-4.17-for-rhel-9-x86_64-rpms

aarch64

rhocp-4.17-for-rhel-9-aarch64-rpms

Create the activation key

Create a new activation key

Navigate to https://console.redhat.com/insights/connector/activation-keys and create a new activation key. Follow the instructions in the wizard.

Refer to the Red Hat documentation for additional information.

Add additional repositories to the key

Once the key is created, click "add repositories". Add all the applicable repositories for all architectures. If you want to build source containers include the corresponding source repositories as well.

redhat-activation-key-configuration
Figure 1. Selecting additional repositories for an activation key

When saved, your key should look something like this:

redhat-activation-key-additional-repositories
Figure 2. Activation Key with additional repositories configured
Note the name of the activation key and the org ID which can be found in the drop-down under your name in the top right corner of the screen. You will need both in a subsequent step to register the container using subscription-manager.

Configure rpm-lockfile-prototype

For this step we will assume that you have source code in your current working directory $(pwd).

  1. Start a new container using the same version of Red Hat Enterprise Linux as what you will be building on and mount your source code directory:

In this example, we’ll using the Red Hat Enterprise Linux 9 Universal Base Image (UBI 9).

podman run --rm -it -v $(pwd):/source:Z registry.access.redhat.com/ubi9

  1. Register with your activation key from the previous step:

subscription-manager register --activationkey="$KEY_NAME" --org="$ORG_ID"
You may see a message saying subscription-manager is operating in container mode. Use your host system to manage subscriptions., which is not applicable if you’re running the container on Fedora or MacOS.

  1. Verify that you have the correct repositories and enable missing source repositories. NOTE: It is normal to only see the repositories for your current architecture at this stage.

[root@ yum.repos.d]# dnf repolist --enabled
Updating Subscription Management repositories.
repo id                                                                                                                           repo name
rhel-9-for-aarch64-appstream-rpms                                                                                                 Red Hat Enterprise Linux 9 for ARM 64 - AppStream (RPMs)
rhel-9-for-aarch64-baseos-rpms                                                                                                    Red Hat Enterprise Linux 9 for ARM 64 - BaseOS (RPMs)
rhocp-4.17-for-rhel-9-aarch64-rpms                                                                                                Red Hat OpenShift Container Platform 4.17 for RHEL 9 ARM 64 (RPMs)
rhocp-4.17-for-rhel-9-aarch64-source-rpms                                                                                         Red Hat OpenShift Container Platform 4.17 for RHEL 9 ARM 64 (Source RPMs)
ubi-9-appstream-rpms                                                                                                              Red Hat Universal Base Image 9 (RPMs) - AppStream
ubi-9-baseos-rpms                                                                                                                 Red Hat Universal Base Image 9 (RPMs) - BaseOS
ubi-9-codeready-builder                                                                                                           Red Hat Universal Base Image 9 (RPMs) - CodeReady Builder`

In the example above, the source RPM repositories are not enabled for the following repositories:

ubi-9-appstream-rpms
ubi-9-baseos-rpms
ubi-9-codeready-builder

You must locate and enable the appropriate RPM repositories in redhat.repo by changing enabled = 0 to enabled = 1.

[rhocp-4.16-for-rhel-9-$basearch-rpms]
name = Red Hat OpenShift Container Platform 4.16 for RHEL 9 $basearch (RPMs)
baseurl = https://cdn.redhat.com/content/dist/layered/rhel9/$basearch/rhocp/4.16/os
enabled = 1
...

[rhocp-4.16-for-rhel-9-$basearch-source-rpms]
name = Red Hat OpenShift Container Platform 4.16 for RHEL 9 $basearch (Source RPMs)
baseurl = https://cdn.redhat.com/content/dist/layered/rhel9/$basearch/rhocp/4.16/source/SRPMS
enabled = 1
...

  1. Install necessary tooling

dnf install -y pip skopeo
pip install --user https://github.com/konflux-ci/rpm-lockfile-prototype/archive/refs/tags/v0.13.1.tar.gz
You can find the latest version of rpm-lockfile-prototype on GitHub, or viewing the repository tags.

  1. Copy the default repository file configured by subscription-manager to the source/ directory

cp /etc/yum.repos.d/redhat.repo /source/redhat.repo

  1. Substitute the current architecture with $basearch in redhat.repo to facilitate fetching for multiple architectures

sed -i "s/$(uname -m)/\$basearch/g" redhat.repo

  1. Authenticate to the Red Hat container registry

skopeo login registry.redhat.io

  1. Configure rpms.in.yaml There are three things to configure:

    1. Add ./redhat.repo under contentOrigin.repofiles in rpms.in.yaml

    2. Add the RPM we want Konflux to prefetch for hermetic builds (openshift-clients)

    3. Configure the enabled architectures

The following is an example of what your rpms.in.yaml file should look like:

contentOrigin:
  # Define at least one source of packages, but you can have as many as you want.
  repofiles:
     - ./redhat.repo

packages:
  # list of rpm names to resolve
  - openshift-clients

#reinstallPackages: []
  # list of rpms already provided in the base image, but which should be
  # reinstalled

arches:
  # The list of architectures can be set in the config file. Any `--arch` option set
  # on the command line will override this list.
  - aarch64
  - x86_64
  # - s390x
  # - ppc64le

context:
    # Alternative to setting command line options. Usually you will only want
    # to include one of these options, with the exception of `flatpak` that
    # can be combined with `image` and `containerfile`
    containerfile: Containerfile
In the source directory for this example there is a Containerfile named Containerfile which starts with the line FROM registry.access.redhat.com/ubi9/ubi, which is the reason why we’re using a RHEL 9 UBI image to generate the lock file.

  1. Create the lock file

cd /source; rpm-lockfile-prototype -f Containerfile rpms.in.yaml

If you encounter SSL errors (Problem with the local SSL certificates), make sure the sslclientkey and sslclientcert options in redhat.repo resolve to the correct path on the file system. These options point to certificates and keys that use a unique identifier (e.g., sslclientcert = /etc/pki/entitlement-host/$ID.pem). You may see SSL issues if you copied a repository configuration file from a different system registered with a different entitlement or activation key.

If successful, you should see a rpms.lock.yaml file in the source directory:

---
lockfileVersion: 1
lockfileVendor: redhat
arches:
- arch: x86_64
  packages:
  - url: https://cdn.redhat.com/content/dist/layered/rhel9/x86_64/rhocp/4.16/os/Packages/o/openshift-clients-4.16.0-202410172045.p0.gcf533b5.assembly.stream.el9.x86_64.rpm
    repoid: rhocp-4.16-for-rhel-9-x86_64-rpms
    size: 54912665
    checksum: sha256:0ffd7347620fd10bb75774520e571702361a6d0352de9112979693d003964038
    name: openshift-clients
    evr: 4.16.0-202410172045.p0.gcf533b5.assembly.stream.el9
    sourcerpm: openshift-clients-4.16.0-202410172045.p0.gcf533b5.assembly.stream.el9.src.rpm
...
If you see warnings like “WARNING:root:No sources found for...” then there is a source repository that still needs to be enabled in your repository configuration. If so, and you need source RPMs, be sure to enable the source RPM repositories in redhat.repo and regenerate the lock file.

Finally, commit the rpms.in.yaml, rpms.lock.yaml and redhat.repo to source control. Konflux will use these files to prefetch RPMs for hermetic builds.