Chapter 6. Configuring the image builder worker for subscription-managed RPM content


The image builder worker builds operating system images for devices, including images from the simplified image building workflow in the Red Hat Edge Manager web console. During each build, the worker installs the agent RPM. To install that RPM from your Red Hat Enterprise Linux subscription instead of the default public repository, configure Kubernetes secrets or Podman volume mounts and Helm values by following this procedure.

  • Red Hat Edge Manager is deployed with the image builder worker enabled. The Helm value imageBuilderWorker.enabled is true by default.
  • A valid Red Hat Enterprise Linux subscription with the Red Hat Edge Manager RPM repository enabled for your architecture. Use the repository identifier that matches your product version and system architecture.
  • Permissions appropriate to your environment: cluster administrator on Red Hat OpenShift Container Platform, cluster administration on other Kubernetes distributions, or root or sudo-capable access on a Red Hat Enterprise Linux host where Red Hat Edge Manager runs with Podman Quadlets.

Before you create the rhel-yum-repos secret, prepare a copy of /etc/yum.repos.d/redhat.repo from a subscribed Red Hat Enterprise Linux host. The file contains entitlement certificate paths such as /etc/pki/entitlement/1234567890-key.pem. After you mount secrets into the worker pod, those paths must use the generic file names that the pod expects.

  1. On a subscribed Red Hat Enterprise Linux host, copy the repository definition file:

    $ cp /etc/yum.repos.d/redhat.repo /tmp/redhat.repo
  2. Replace the host-specific entitlement paths with generic paths:

    $ sed -i \
      -e 's|/etc/pki/entitlement/[0-9]*-key.pem|/etc/pki/entitlement/entitlement-key.pem|g' \
      -e 's|/etc/pki/entitlement/[0-9]*.pem|/etc/pki/entitlement/entitlement.pem|g' \
      /tmp/redhat.repo
  3. Keep /tmp/redhat.repo for the secret creation steps in the following sections.
Note

The Subscription Manager CA certificate at /etc/rhsm/ca/redhat-uep.pem is required so that dnf can verify TLS to cdn.redhat.com. Configure the rhsmCaSecretName Helm value so that this content is mounted at /etc/rhsm/ca in the worker pod.

On clusters where Red Hat Enterprise Linux entitlements are in use, OpenShift exposes entitlement data in the etc-pki-entitlement secret in the openshift-config-managed namespace.

  • The OpenShift CLI (oc) is installed and you are authenticated to the cluster.
  • You prepared /tmp/redhat.repo as described in Preparing the redhat.repo file for a Kubernetes secret.

    1. Set your Red Hat Edge Manager project namespace:

      $ export NAMESPACE=<project_name>

      Replace <project_name> with the namespace where Red Hat Edge Manager is installed.

    2. Copy the entitlement secret into that namespace:

      $ oc get secret etc-pki-entitlement -n openshift-config-managed -o yaml | \
        sed "s/namespace: openshift-config-managed/namespace: ${NAMESPACE}/" | \
        oc apply -f -
    3. Create a secret that contains the sanitized repository definition:

      $ oc create secret generic rhel-yum-repos -n ${NAMESPACE} \
        --from-file=redhat.repo=/tmp/redhat.repo
    4. Create a secret from the Subscription Manager configuration directory. Run this command on a system where /etc/rhsm/ is available (typically a subscribed Red Hat Enterprise Linux host with oc configured for the cluster), or copy /etc/rhsm/ to your workstation and adjust the path in the command:

      $ oc create secret generic rhel-rhsm -n ${NAMESPACE} --from-file=/etc/rhsm/
    5. Create a secret that contains the Subscription Manager CA certificates:

      $ oc create secret generic rhel-rhsm-ca -n ${NAMESPACE} --from-file=/etc/rhsm/ca/
    6. Add the following values to your Red Hat Edge Manager Helm release. In the Red Hat OpenShift Container Platform web console, navigate to Helm Releases, locate your release, select Upgrade, and edit the YAML values. Merge the example fields with your existing configuration.

      imageBuilderWorker values for Red Hat OpenShift Container Platform

      imageBuilderWorker:
        entitlementCertsSecretName: "etc-pki-entitlement"
        yumReposSecretName: "rhel-yum-repos"
        rhsmSecretName: "rhel-rhsm"
        rhsmCaSecretName: "rhel-rhsm-ca"
        rpmRepoAdd: false
        rpmRepoEnable: "edge-manager-1.1-for-rhel-9-x86_64-rpms"

      Replace rpmRepoEnable with your enabled repository identifier if it differs.

      Note
      • Setting rpmRepoAdd to false prevents adding an external repository URL because repository definitions come from mounted secrets.
      • rpmRepoEnable sets the repository that dnf uses when it installs the agent RPM (--enablerepo).
    7. Complete the upgrade so that the chart is redeployed. In the console, click Upgrade. If you use the CLI or GitOps, apply the equivalent change.

6.3. Configuring on other Kubernetes distributions

  • The Kubernetes CLI (kubectl) is installed and configured for the cluster where Red Hat Edge Manager runs.
  • You prepared /tmp/redhat.repo as described in Preparing the redhat.repo file for a Kubernetes secret.
  • You can run commands on a subscribed Red Hat Enterprise Linux host (or equivalent) to read /etc/pki/entitlement/ and /etc/rhsm/.

    1. Create the secrets in the same namespace as your Red Hat Edge Manager release. Replace <project_name> with that namespace.

      $ kubectl create secret generic rhel-entitlement -n <project_name> \
        --from-file=/etc/pki/entitlement/
      
      $ kubectl create secret generic rhel-yum-repos -n <project_name> \
        --from-file=redhat.repo=/tmp/redhat.repo
      
      $ kubectl create secret generic rhel-rhsm -n <project_name> \
        --from-file=/etc/rhsm/
      
      $ kubectl create secret generic rhel-rhsm-ca -n <project_name> \
        --from-file=/etc/rhsm/ca/
    2. Update your Helm values for Red Hat Edge Manager to include the following imageBuilderWorker settings (merge with your existing values):

      imageBuilderWorker values for Kubernetes

      imageBuilderWorker:
        entitlementCertsSecretName: "rhel-entitlement"
        yumReposSecretName: "rhel-yum-repos"
        rhsmSecretName: "rhel-rhsm"
        rhsmCaSecretName: "rhel-rhsm-ca"
        rpmRepoAdd: false
        rpmRepoEnable: "edge-manager-1.1-for-rhel-9-x86_64-rpms"

    3. Redeploy or upgrade the Helm release so the image builder worker uses the new configuration.

When Red Hat Edge Manager runs on Red Hat Enterprise Linux using Podman Quadlets, mount subscription data from the host into the image builder worker container and disable the default repository URL step.

  • Red Hat Edge Manager services are installed from the flightctl-services package and run under Podman.
  • The host has an active Red Hat Enterprise Linux subscription with the Red Hat Edge Manager repository enabled.

    1. Edit the image builder worker container unit file. The path can vary by package version; a typical path is /usr/share/containers/systemd/flightctl-imagebuilder-worker.container. In the [Container] section, add read-only volume mounts:

      Volume=/etc/pki/entitlement:/etc/pki/entitlement:ro,z
      Volume=/etc/yum.repos.d:/etc/yum.repos.d:ro,z
      Volume=/etc/rhsm/:/etc/rhsm/:ro,z
    2. Edit /etc/flightctl/service-config.yaml and set the following under imagebuilderWorker (adjust the path if your installation differs):

      imagebuilderWorker:
        rpmRepoAdd: false
        rpmRepoEnable: "edge-manager-1.1-for-rhel-9-x86_64-rpms"
    3. Reload systemd and restart the worker:

      $ sudo systemctl daemon-reload
      $ sudo systemctl restart flightctl-imagebuilder-worker.service

The following Helm values control how the image builder worker accesses RPM content. Defaults apply when you use the public repository; set the values below when you use subscription-managed repositories.

Expand
ParameterDefaultDescription

imageBuilderWorker.rpmRepoAdd

true

Set to false when repositories are supplied by secrets or host mounts.

imageBuilderWorker.rpmRepoEnable

empty

Repository identifier passed to dnf with --enablerepo when installing the agent RPM.

imageBuilderWorker.entitlementCertsSecretName

empty

Kubernetes secret mounted at /etc/pki/entitlement.

imageBuilderWorker.yumReposSecretName

empty

Kubernetes secret whose files appear under /etc/yum.repos.d.

imageBuilderWorker.rhsmSecretName

empty

Kubernetes secret that contains Subscription Manager configuration under /etc/rhsm.

imageBuilderWorker.rhsmCaSecretName

empty

Kubernetes secret mounted at /etc/rhsm/ca (must include redhat-uep.pem for CDN TLS verification).

6.6. Troubleshooting

If image builds fail with a package or subscription error, use the following checks:

  • Package not found: Confirm network access to Red Hat CDN or your mirrors. Verify that rpmRepoEnable matches a repository that is enabled for your entitlement.
  • Subscription or entitlement errors: On Kubernetes, verify that each secret exists in the release namespace and that the entitlement key paths in redhat.repo match the sanitized names. On Red Hat Enterprise Linux, run sudo subscription-manager status on the host.
  • Worker logs: On Kubernetes, run kubectl logs deployment/flightctl-imagebuilder-worker -n <project_name>. On Red Hat Enterprise Linux, run sudo journalctl -u flightctl-imagebuilder-worker.service.
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

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.

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 Documentation

Legal Notice

Theme

© 2026 Red Hat
Back to top