From 255a6a335b2add0a4466f78fcbdf70b91bf862eb Mon Sep 17 00:00:00 2001 From: Alexey Loubyansky Date: Tue, 22 Oct 2024 15:16:15 +0200 Subject: [PATCH] Cachi2 Lock File generator doc --- guide/build-config.md | 23 +++++++++++++++++++++++ guide/pig.md | 38 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+) diff --git a/guide/build-config.md b/guide/build-config.md index c17cf7123..4d7d81190 100644 --- a/guide/build-config.md +++ b/guide/build-config.md @@ -489,6 +489,29 @@ Note that the following configuration options are currently **not** supported by To test `BOM` strategy locally, an existing config using `RESOLVE_ONLY` should simply be updated to use the `BOM` strategy. Here is a sample command line that generates RHBQ 3.2.9 Maven repository ZIP: +###### Cachi2 Lock File Generation + +The `BOM` strategy offers an option to capture the resolved artifacts with the `redhat` version qualifier and generate a Cachi2 Lock File that can be used later to prefetch the generated MRRC ZIP content into a Konflux pipeline for container image building or an MRRC release process. + +> [!NOTE] +> It's also possible to configure the `cachi2LockFile` addon as an alternative. The difference between these options is that the addon will be deriving artifact coordinates (groupId, artifactId, classifier, extension and version) from the file names found in the ZIP (which in certain edge cases might not be reliable), while the BOM strategy will capture all the artifact coordinates during the resolution process. + +To enable Cachi2 Lock File generation the `cachi2LockFile` parameter has to be set to the desired target file path. For example + +```yaml +flow: + licensesGeneration: + strategy: GENERATE + repositoryGeneration: + strategy: BOM + parameters: + bomGavs: >- + com.redhat.quarkus.platform:quarkus-bom:{{quarkusPlatformVersion}} + cachi2LockFile: extras/quarkus-platform-{{quarkusPlatformVersion}}-cachi2-lockfile.yaml +``` + +With the configuration above, the Cachi2 Lock File will be saved in the `{RELEASE_DIR}/extras/quarkus-platform-{QUARKUS_PLATFORM_VERSION}-cachi2-lockfile.yaml`. + ``` java -jar bacon.jar pig run --clean --skipBuilds --skipBranchCheck --skipPncUpdate --skipLicenses --skipSources --releaseStorageUrl https://download.eng.bos.redhat.com/rcm-guest/staging/quarkus config-dir/ --targetPath deliverables ``` diff --git a/guide/pig.md b/guide/pig.md index 5d9f77c3d..5d508ca48 100644 --- a/guide/pig.md +++ b/guide/pig.md @@ -33,6 +33,11 @@ The `configure` phase pushes all the settings in the YAML file to PNC, and the ` bacon pig ... ``` +## Other PiG commands + +The following `pig` subcommands are available but not tied to any specific phase: + +- cachi2lockfile # Configuration @@ -294,8 +299,41 @@ addons: #### Using Defaults To use default value for an optional parameter leave that parameter undefined in the addons section of your build-config.yaml file. +### Cachi2 Lock File Generator + +This add-on generates a Cachi2 Lock File for the produced Maven repository ZIP (regardless which strategy was used to generate it). Cachi2 Lock Files can be used to prefetch Maven content to Konflux pipelines for container image and MRRC release processes. + +The add-on can be configured in the following way: + +``` +addons: + cachi2LockFile: + filename: mrrc-cachi2-lockfile.yaml +``` + +The `filename` parameter is optional and defaults to `cachi2lockfile.yaml` if not configured. The file will be stored under the `extras` directory. + {% endraw %} +## cachi2lockfile command + +This `pig cachi2lockfile` CLI command allows generating a Cachi2 lockfile for a given Maven repository. The command will not perform any Maven artifact resolution, it will simply describe the content of a Maven repository in the Cachi2 lock file format. + +The command accepts ZIP files and/or directories that include Maven repository content under `maven-repository` subdirectory (to be compliant with the way Bacon generates Maven repository ZIPs). For example: + +``` +bacon pig cachi2lockfile rh-quarkus-platform-3.15.2.CR1-maven-repository.zip +``` + +Multiple repository paths (including a mix of directories and ZIPs) can be provided using comma as a separator. + +By default, the generated lock file will be named `artifacts.lock.yaml`, since this is what Cachi2 to will expect by default. A different file name can be specified by adding the `--output` argument with the desired value. + +Other command options include: + +* `--maven-repository-url` - the desired value of the Maven repository URL to record for each artifact. The default value will match the one configured in the local Bacon config; +* `--preferred-checksum-alg` - the lock file format expects a single checksum. By default, the tool will use the highest version of the `SHA` checksum available in the Maven repository. This option allows to specify an alternative checksum algorithm (assuming it's available in the repository), if the default is not good enough. + ## PiG Export Feature ### Build Configuration Export