OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history bug_report picture_as_pdf
×

Using Red Hat subscriptions in builds

Creating an image stream tag for the Red Hat Universal Base Image

To install Red Hat Enterprise Linux (RHEL) packages within a build, you can create an image stream tag to reference the Red Hat Universal Base Image (UBI).

To make the UBI available in every project in the cluster, add the image stream tag to the openshift namespace. Otherwise, to make it available in a specific project, add the image stream tag to that project.

Image stream tags grant access to the UBI by using the registry.redhat.io credentials that are present in the install pull secret, without exposing the pull secret to other users. This method is more convenient than requiring each developer to install pull secrets with registry.redhat.io credentials in each project.

Procedure

  • To create an ImageStreamTag in the openshift namespace, so it is available to developers in all projects, enter:

    $ oc tag --source=docker registry.redhat.io/ubi9/ubi:latest ubi9:latest -n openshift

    You can alternatively apply the following YAML to create an ImageStreamTag in the openshift namespace:

    apiVersion: image.openshift.io/v1
kind: ImageStream
metadata:
  name: ubi9
  namespace: openshift
spec:
  tags:
  - from:
      kind: DockerImage
      name: registry.redhat.io/ubi9/ubi:latest
    name: latest
    referencePolicy:
      type: Source

  • To create an ImageStreamTag in a single project, enter:

    $ oc tag --source=docker registry.redhat.io/ubi9/ubi:latest ubi:latest

    You can alternatively apply the following YAML to create an ImageStreamTag in a single project:

    apiVersion: image.openshift.io/v1
kind: ImageStream
metadata:
  name: ubi9
spec:
  tags:
  - from:
      kind: DockerImage
      name: registry.redhat.io/ubi9/ubi:latest
    name: latest
    referencePolicy:
      type: Source

Adding subscription entitlements as a build secret

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 Enterprise Linux (RHEL) package repositories through your subscription.

The entitlement secret to access these repositories is automatically created by the Insights Operator when your cluster is subscribed.

You must be a cluster administrator or have permission to access secrets in the openshift-config-managed project.
Procedure

  1. Copy the entitlement secret from the openshift-config-managed namespace to the build’s namespace:

    $ cat << EOF > secret-template.txt
kind: Secret
apiVersion: v1
metadata:
  name: etc-pki-entitlement
type: Opaque
data: {{ range \$key, \$value := .data }}
  {{ \$key }}: {{ \$value }} {{ end }}
EOF
$ oc get secret etc-pki-entitlement -n openshift-config-managed -o=go-template-file --template=secret-template.txt | oc apply -f -

  2. Add the etc-pki-entitlement secret as a build volume in the build configuration’s Docker strategy:

    strategy:
  dockerStrategy:
    from:
      kind: ImageStreamTag
      name: ubi9:latest
    volumes:
    - name: etc-pki-entitlement
      mounts:
      - destinationPath: /etc/pki/entitlement
      source:
        type: Secret
        secret:
          secretName: etc-pki-entitlement

Running builds with Subscription Manager

Docker builds using Subscription Manager

Docker strategy builds can use yum or dnf to install additional Red Hat Enterprise Linux (RHEL) packages.

Prerequisites

The entitlement keys must be added as build strategy volumes.

Procedure

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

FROM registry.redhat.io/ubi9/ubi:latest
RUN rm -rf /etc/rhsm-host (1)
RUN yum --enablerepo=codeready-builder-for-rhel-9-x86_64-rpms install \ (2)
    nss_wrapper \
    uid_wrapper -y && \
    yum clean all -y
RUN ln -s /run/secrets/rhsm /etc/rhsm-host (3)
1 You must include the command to remove the /etc/rhsm-host directory and all its contents in your Dockerfile before executing any yum or dnf commands.
2 Use the Red Hat Package Browser to find the correct repositories for your installed packages.
3 You must restore the /etc/rhsm-host symbolic link to keep your image compatible with other Red Hat container images.

Running builds with Red Hat Satellite subscriptions

Adding Red Hat Satellite configurations to builds

Builds that use Red Hat 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
Procedure

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

    $ oc create configmap yum-repos-d --from-file /path/to/satellite.repo

  2. Add the Satellite repository configuration and entitlement key as a build volumes:

    strategy:
  dockerStrategy:
    from:
      kind: ImageStreamTag
      name: ubi9:latest
    volumes:
    - name: yum-repos-d
      mounts:
      - destinationPath: /etc/yum.repos.d
      source:
        type: ConfigMap
        configMap:
          name: yum-repos-d
    - name: etc-pki-entitlement
      mounts:
      - destinationPath: /etc/pki/entitlement
      source:
        type: Secret
        secret:
          secretName: etc-pki-entitlement

Docker builds using Red Hat Satellite subscriptions

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

Prerequisites

  • You have added the entitlement keys and Satellite repository configurations as build volumes.

Procedure

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

FROM registry.redhat.io/ubi9/ubi:latest
RUN rm -rf /etc/rhsm-host (1)
RUN yum --enablerepo=codeready-builder-for-rhel-9-x86_64-rpms install \ (2)
    nss_wrapper \
    uid_wrapper -y && \
    yum clean all -y
RUN ln -s /run/secrets/rhsm /etc/rhsm-host (3)
1 You must include the command to remove the /etc/rhsm-host directory and all its contents in your Dockerfile before executing any yum or dnf commands.
2 Contact your Satellite system administrator to find the correct repositories for the build’s installed packages.
3 You must restore the /etc/rhsm-host symbolic link to keep your image compatible with other Red Hat container images.
Additional resources

Running builds using SharedSecret objects

You can use a SharedSecret object to securely access the entitlement keys of a cluster in builds.

The SharedSecret object allows you to share and synchronize secrets across namespaces.

Shared Resource CSI Driver is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.
Prerequisites

  • You have enabled the TechPreviewNoUpgrade feature set by using the feature gates. For more information, see Enabling features using feature gates.

  • You must have permission to perform the following actions:

    • Create build configs and start builds.

    • Discover which SharedSecret CR instances are available by entering the oc get sharedsecrets command and getting a non-empty list back.

    • Determine if the builder service account available to you in your namespace is allowed to use the given SharedSecret CR instance. In other words, you can run oc adm policy who-can use <identifier of specific SharedSecret> to see if the builder service account in your namespace is listed.

If neither of the last two prerequisites in this list are met, establish, or ask someone to establish, the necessary role-based access control (RBAC) so that you can discover SharedSecret CR instances and enable service accounts to use SharedSecret CR instances.
Procedure

  1. Use oc apply to create a SharedSecret object instance with the cluster’s entitlement secret.

    You must have cluster administrator permissions to create SharedSecret objects.
    Example oc apply -f command with YAML Role object definition
    $ oc apply -f - <<EOF
kind: SharedSecret
apiVersion: sharedresource.openshift.io/v1alpha1
metadata:
  name: etc-pki-entitlement
spec:
  secretRef:
    name: etc-pki-entitlement
    namespace: openshift-config-managed
EOF

  2. Create a role to grant the builder service account permission to access the SharedSecret object:

    Example oc apply -f command
    $ oc apply -f - <<EOF
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: builder-etc-pki-entitlement
  namespace: build-namespace
rules:
  - apiGroups:
      - sharedresource.openshift.io
    resources:
      - sharedsecrets
    resourceNames:
      - etc-pki-entitlement
    verbs:
      - use
EOF

  3. Create a RoleBinding object that grants the builder service account permission to access the SharedSecret object by running the following command:

    Example oc create rolebinding command
    $ oc create rolebinding builder-etc-pki-entitlement --role=builder-etc-pki-entitlement --serviceaccount=build-namespace:builder

  4. Add the entitlement secret to your BuildConfig object by using a CSI volume mount:

    Example YAML BuildConfig object definition
    apiVersion: build.openshift.io/v1
kind: BuildConfig
metadata:
  name: uid-wrapper-rhel9
  namespace: build-namespace
spec:
  runPolicy: Serial
  source:
    dockerfile: |
      FROM registry.redhat.io/ubi9/ubi:latest
      RUN rm -rf /etc/rhsm-host (1)
      RUN yum --enablerepo=codeready-builder-for-rhel-9-x86_64-rpms install \ (2)
          nss_wrapper \
          uid_wrapper -y && \
          yum clean all -y
      RUN ln -s /run/secrets/rhsm /etc/rhsm-host (3)
  strategy:
    type: Docker
    dockerStrategy:
      volumes:
        - mounts:
            - destinationPath: "/etc/pki/entitlement"
          name: etc-pki-entitlement
          source:
            csi:
              driver: csi.sharedresource.openshift.io
              readOnly: true (4)
              volumeAttributes:
                sharedSecret: etc-pki-entitlement (5)
            type: CSI
    1 You must include the command to remove the /etc/rhsm-host directory and all its contents in the Dockerfile before executing any yum or dnf commands.
    2 Use the Red Hat Package Browser to find the correct repositories for your installed packages.
    3 You must restore the /etc/rhsm-host symbolic link to keep your image compatible with other Red Hat container images.
    4 You must set readOnly to true to mount the shared resource in the build.
    5 Reference the name of the SharedSecret object to include it in the build.

  5. Start a build from the BuildConfig object and follow the logs using the oc command.

    $ oc start-build uid-wrapper-rhel9 -n build-namespace -F

Additional resources