konflux-ci/clair-in-ci-db/hermetic-build-deps

Hermetic Build Dependencies

Overview

This repo uses Konflux hermetic builds — the build-container task runs with no network access. All external dependencies (RPMs, GPG keys) must be prefetched by Cachi2 during the prefetch-dependencies task and made available offline. Four files control this system and must stay in sync.

When to Use

• Adding a new RPM package to the image
• Updating a pinned RPM version
• Prefetch-dependencies task is failing
• Understanding how Dockerfile installs relate to lock files
• Updating the EPEL GPG key or repository configuration

Dependency Files

How They Work Together

rpms.in.yaml          ─── declares "I need jq" + points to epel.repo
    │
    ├─ rpms.lock.yaml  ─── resolves jq to exact version + checksum from repos
    │
    └─ epel.repo       ─── provides the EPEL 8 metalink URL for resolution
 
artifacts.lock.yaml    ─── pins the EPEL GPG key + individual RPM downloads
                           (these are fetched as "generic" artifacts by Cachi2)

In the Tekton Pipeline

The prefetch-input parameter tells Cachi2 what to prefetch:

prefetch-input: '[{"type": "rpm", "path": "."}, {"type": "generic", "path": "."}]'

• type: rpm — reads rpms.in.yaml → resolves via rpms.lock.yaml → downloads RPMs
• type: generic — reads artifacts.lock.yaml → downloads listed artifacts by URL + checksum

In the Dockerfile

Prefetched artifacts land in /cachi2/output/deps/:

RUN rpm --import /cachi2/output/deps/generic/RPM-GPG-KEY-EPEL-8 && \
    microdnf -y --setopt=tsflags=nodocs install \
    --setopt=install_weak_deps=0 \
    jq-1.6-11.el8_10 && \
    microdnf clean all

Key points:

• GPG key is imported from the Cachi2 generic artifacts path
• microdnf install uses exact version (jq-1.6-11.el8_10) matching rpms.lock.yaml
• --setopt=tsflags=nodocs and --setopt=install_weak_deps=0 minimize image size

Current Dependencies

RPMs (via rpms.in.yaml + rpms.lock.yaml)

Generic Artifacts (via artifacts.lock.yaml)

How to Add a New RPM

1. Add the package name to rpms.in.yaml:

``yaml packages: [jq, newpackage] ``

1. Regenerate the lock file using rpm-lockfile-prototype:

``bash rpm-lockfile-prototype --image <BASE_IMAGE> rpms.in.yaml ` This resolves packages against the base image, producing rpms.lock.yaml` with exact versions and checksums. See Konflux docs for details.

1. If the RPM or its dependencies need to be pinned as generic artifacts, add entries to artifacts.lock.yaml with the download URL and SHA-256 checksum

1. Update the Dockerfile to install the new package with its exact version:

``dockerfile microdnf -y --setopt=tsflags=nodocs install \ --setopt=install_weak_deps=0 \ jq-1.6-11.el8_10 \ newpackage-x.y-z.el8 ``

1. Keep it as a single RUN layer to minimize image size

How to Update an Existing RPM Version

1. Update the version in rpms.lock.yaml (or regenerate with Cachi2)
2. Update the checksum in artifacts.lock.yaml if the RPM is also listed there
3. Update the exact version string in the Dockerfile microdnf install command
4. All three must match

Common Mistakes