diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index bc70c0c..def5cee 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -24,6 +24,11 @@ "source": "./plugins/ci", "description": "A plugin to work with OpenShift CI" }, + { + "name": "fbc-art-images", + "source": "./plugins/fbc-art-images", + "description": "A plugin for testing operators built in FBC ([File Based Catalog](https://olm.operatorframework.io/docs/reference/file-based-catalogs/) by Konflux with art-images-share repository. Requires oras CLI." + }, { "name": "doc", "source": "./plugins/doc", diff --git a/plugins/fbc-art-images/.claude-plugin/plugin.json b/plugins/fbc-art-images/.claude-plugin/plugin.json new file mode 100644 index 0000000..eba3ca2 --- /dev/null +++ b/plugins/fbc-art-images/.claude-plugin/plugin.json @@ -0,0 +1,8 @@ +{ + "name": "fbc-art-images", + "description": "Assists with testing operators built in [FBC](https://olm.operatorframework.io/docs/reference/file-based-catalogs/) (File Based Catalog) by Konflux (quay.io/redhat-user-workloads/ocp-art-tenant/art-fbc) with quay.io/redhat-user-workloads/ocp-art-tenant/art-images-share image repository. Requires oras CLI for image discovery.", + "version": "0.0.1", + "author": { + "name": "sherine-k" + } +} diff --git a/plugins/fbc-art-images/README.md b/plugins/fbc-art-images/README.md new file mode 100644 index 0000000..6447e2d --- /dev/null +++ b/plugins/fbc-art-images/README.md @@ -0,0 +1,268 @@ +# FBC Art Images Plugin + +A Claude Code plugin for testing operators built in FBC (File-Based Catalog) by Konflux. This plugin automates the generation of Kubernetes manifests and cluster configuration needed to test operators using images from the art-image-share registry. + +## Overview + +When testing OpenShift operators built with Konflux's FBC tooling, you need to: + +1. Create a **CatalogSource** pointing to the FBC index image +2. Configure **IDMS** (ImageDigestMirrorSet) to mirror images from art-image-share +3. Update the cluster **pull-secret** with credentials to access art-image-share registry + +This plugin automates all three steps, providing both a complete setup command and individual commands for granular control. + +## Prerequisites + +- OpenShift cluster access (4.14+) +- `oc` CLI installed and authenticated +- **`oras` CLI** installed for image discovery ([installation guide](https://oras.land/docs/installation)) +- `jq` command-line JSON processor +- **Pull-secret configured**: The cluster pull-secret must include credentials for `quay.io/redhat-user-workloads/ocp-art-tenant/art-images-share`. See `pull-secret.md` in this plugin directory for detailed instructions on obtaining and configuring the pull-secret. +- Cluster-admin or similar permissions (for pull-secret and IDMS updates) + +## Commands + +### `/fbc-art-images:setup` + +Complete setup that generates all three manifests and optionally applies them. + +**Usage:** +``` +/fbc-art-images:setup +``` + +**Example:** +``` +/fbc-art-images:setup 4.20 amq-broker-rhel9 +``` + +**What it does:** +1. Generates CatalogSource manifest for the operator +2. Generates IDMS manifest for registry mirroring +3. Optionally applies all manifests to the cluster + +**Output files:** +- `.work/fbc-art-images/_/catalogsource.yaml` +- `.work/fbc-art-images/_/idms.yaml` + +--- + +### `/fbc-art-images:catalog-source` + +Generate only the CatalogSource manifest. + +**Usage:** +``` +/fbc-art-images:catalog-source +``` + +**Example:** +``` +/fbc-art-images:catalog-source 4.20 amq-broker-rhel9 +``` + +**What it does:** +- Creates a CatalogSource pointing to the FBC index image +- Uses the Konflux FBC image pattern: `quay.io/redhat-user-workloads/ocp-art-tenant/art-fbc:ocp____` + +--- + +### `/fbc-art-images:idms` + +Generate only the IDMS manifest for registry mirroring. + +**Usage:** +``` +/fbc-art-images:idms +``` + +**Example:** +``` +/fbc-art-images:idms 4.20 amq-broker-rhel9 +``` + +**What it does:** +- Discovers all related operator images from the FBC image using `oras` CLI +- Creates ImageDigestMirrorSet to mirror each discovered image to art-images-share repository +- Generates operator-specific IDMS named `art-image-share--` + +**Important:** +- Requires `oras` CLI to be installed +- Applying an IDMS triggers MachineConfig updates which will cause cluster nodes to restart sequentially (20-30 minutes) + +--- + +## Typical Workflow + +### Quick Setup (Recommended) + +**Before you begin**, ensure the pull-secret is configured (see `pull-secret.md` for instructions). + +For most use cases, use the setup command: + +```bash +# Run the setup command +/fbc-art-images:setup 4.20 amq-broker-rhel9 + +# Review generated manifests +# Choose to apply or manually review +``` + +### Manual Step-by-Step Setup + +For more control, use individual commands: + +```bash +# 1. Configure pull-secret first (one time per cluster) +# See pull-secret.md for detailed instructions + +# 2. Generate and apply IDMS (triggers node restarts) +/fbc-art-images:idms 4.20 amq-broker-rhel9 + +# 3. Wait for nodes to finish updating (20-30 minutes) +oc get mcp +oc get nodes + +# 4. Generate and apply CatalogSource +/fbc-art-images:catalog-source 4.20 amq-broker-rhel9 + +# 5. Verify CatalogSource is ready +oc get catalogsource test-4.20-amq-broker-rhel9-catalog -n openshift-marketplace +``` + +## After Setup + +Once the setup is complete, you can: + +1. **View available operators:** + ```bash + oc get packagemanifests -n openshift-marketplace | grep + ``` + +2. **Create a Subscription to install the operator:** + ```yaml + apiVersion: operators.coreos.com/v1alpha1 + kind: Subscription + metadata: + name: + namespace: openshift-operators + spec: + channel: stable + name: + source: -catalog + sourceNamespace: openshift-marketplace + ``` + +3. **Monitor the installation:** + ```bash + oc get csv -n openshift-operators + oc get installplan -n openshift-operators + ``` + +## Troubleshooting + +### CatalogSource not ready + +```bash +# Check CatalogSource status +oc get catalogsource -catalog -n openshift-marketplace -o yaml + +# Check catalog pod logs +oc logs -n openshift-marketplace -l olm.catalogSource=-catalog + +# Common issues: +# - Image pull errors (check pull-secret) +# - IDMS not applied or nodes not updated +# - Network connectivity to quay.io +``` + +### Image pull errors + +```bash +# Verify pull-secret has art-image-share credentials +# (Should contain quay.io/redhat-user-workloads/ocp-art-tenant/art-images-share) +oc get secret pull-secret -n openshift-config -o jsonpath='{.data.\.dockerconfigjson}' | base64 -d | jq . + +# Verify IDMS is applied +oc get imagedigestmirrorset art-image-share-- -o yaml + +# Check node status (nodes must complete MachineConfig updates) +oc get nodes +oc get mcp +``` + +### MachineConfig updates stuck + +```bash +# Check MachineConfigPool status +oc get mcp -o wide + +# Check machine-config-operator logs +oc logs -n openshift-machine-config-operator -l k8s-app=machine-config-controller + +# If nodes are stuck, check specific node: +oc describe node +``` + +## Security Notes + +- **Credentials**: The pull-secret contains sensitive credentials. Handle with care. See `pull-secret.md` for details. +- **File permissions**: Generated files should have restricted permissions (600) +- **Clean up**: Consider deleting intermediate files after applying manifests + +## FBC Image Naming Convention + +The plugin uses the Konflux FBC image naming convention for per-operator catalogs: + +``` +quay.io/redhat-user-workloads/ocp-art-tenant/art-fbc:ocp____ +``` + +Examples: +- OCP 4.20, AMQ Broker: `quay.io/redhat-user-workloads/ocp-art-tenant/art-fbc:ocp__4.20__amq-broker-rhel9` +- OCP 4.19, Advanced Cluster Management: `quay.io/redhat-user-workloads/ocp-art-tenant/art-fbc:ocp__4.19__advanced-cluster-management` +- OCP 4.18, Kubernetes NMState: `quay.io/redhat-user-workloads/ocp-art-tenant/art-fbc:ocp__4.18__kubernetes-nmstate-rhel9-operator` + +## Files Created + +Generated files are organized under `.work/fbc-art-images/`: + +``` +.work/fbc-art-images/ +├── _/ +│ ├── catalogsource.yaml # CatalogSource manifest +│ ├── idms.yaml # ImageDigestMirrorSet manifest +│ ├── related-images-list.txt # List of discovered operator images +│ └── related-images.json # Raw related images data from oras + +``` + +Example for OCP 4.20 with amq-broker-rhel9: +``` +.work/fbc-art-images/ +├── 4.20_amq-broker-rhel9/ +│ ├── catalogsource.yaml +│ ├── idms.yaml +│ ├── related-images-list.txt +│ └── related-images.json +``` + +## Related Documentation + +- [Replacing pre-releases with FBCs](https://docs.google.com/document/d/1YpMZrKUHQG1QAVstVY4Z7RvM3jyZec6sMSCYoNOAaA8/edit?tab=t.0) +- [ORAS CLI](https://oras.land/) - OCI Registry As Storage CLI for image artifact discovery +- [Konflux Documentation](https://konflux-ci.dev/) +- [OpenShift Operator Lifecycle Manager](https://docs.openshift.com/container-platform/latest/operators/understanding/olm/olm-understanding-olm.html) +- [ImageDigestMirrorSet](https://docs.openshift.com/container-platform/latest/openshift_images/image-configuration.html#images-configuration-registry-mirror_image-configuration) +- [CatalogSource](https://olm.operatorframework.io/docs/concepts/crds/catalogsource/) + +## Contributing + +This plugin is part of the [ai-helpers](https://github.com/openshift-eng/ai-helpers) repository. Contributions are welcome! + +## Support + +For issues or questions: +- GitHub Issues: https://github.com/openshift-eng/ai-helpers/issues +- Plugin Repository: https://github.com/openshift-eng/ai-helpers diff --git a/plugins/fbc-art-images/commands/catalog-source.md b/plugins/fbc-art-images/commands/catalog-source.md new file mode 100644 index 0000000..384aece --- /dev/null +++ b/plugins/fbc-art-images/commands/catalog-source.md @@ -0,0 +1,106 @@ +--- +description: Generate CatalogSource manifest for testing operators built in Konflux +argument-hint: +--- + +## Name +fbc-art-images:catalog-source + +## Synopsis +``` +/fbc-art-images:catalog-source +``` + +## Description +The `fbc-art-images:catalog-source` command generates a CatalogSource manifest for testing operators built in FBC (File-Based Catalog) by Konflux. This command creates only the CatalogSource manifest, allowing users to have fine-grained control over the setup process. + +The CatalogSource points to the FBC image in the OpenShift release registry, making the operator available in the cluster's OperatorHub. + +## Implementation + +### Step 1: Validate Inputs +- Verify `$1` (ocp-version) is provided and follows the format `X.Y` (e.g., "4.18") +- Verify `$2` (operator-name) is provided and is a valid operator name (e.g, "kubernetes-nmstate-rhel9-operator") + +### Step 2: Generate CatalogSource Manifest +- Invoke the **generate-catalog-source** skill with the provided OCP version and operator name +- See detailed implementation: `plugins/fbc-art-images/skills/generate-catalog-source/SKILL.md` +- The skill will: + - Construct the FBC image URL + - Create the working directory (`.work/fbc-art-images/_/`) + - Generate the CatalogSource manifest at `catalogsource.yaml` + +### Step 3: Display Manifest to User +- Show the generated manifest content +- Display the file path: `.work/fbc-art-images/_/catalogsource.yaml` +- Ask if the user wants to apply the manifest: + ``` + CatalogSource manifest generated at: + .work/fbc-art-images/_/catalogsource.yaml + + Apply this manifest now? [y/n] + ``` + +### Step 4: Apply Manifest (if requested) +- If user confirms, apply the manifest: + ```bash + oc apply -f .work/fbc-art-images/_/catalogsource.yaml + ``` +- Wait for the CatalogSource to become ready: + ```bash + oc wait --for=condition=Ready catalogsource/test---catalog -n openshift-marketplace --timeout=5m + ``` +- Display success message: + ``` + CatalogSource applied successfully! + + Check the status: + oc get catalogsource test---catalog -n openshift-marketplace + + View available operators: + oc get packagemanifests -n openshift-marketplace | grep test---catalog + ``` + +### Error Handling +- **Invalid OCP version**: Show error and supported format (X.Y) +- **Missing operator name**: Prompt user to provide operator name +- **No cluster access**: Guide user to run `oc login` +- **CatalogSource not ready**: Show pod logs and troubleshooting steps +- **Image pull errors**: Suggest checking pull-secret and IDMS configuration + +## Return Value +- **Success**: Displays manifest location and optionally applies it +- **File created**: `.work/fbc-art-images/_/catalogsource.yaml` + +## Examples + +1. **Generate CatalogSource for AMQ broker on OCP 4.20**: + ``` + /fbc-art-images:catalog-source 4.20 amq-broker-rhel9 + ``` + Output: + ``` + CatalogSource manifest generated for amq-broker-rhel9 (OCP 4.20) + File: .work/fbc-art-images/4.20_amq-broker-rhel9/catalogsource.yaml + + Apply this manifest now? [y/n] + ``` + +2. **Generate CatalogSource for Compliance Operator on OCP 4.17**: + ``` + /fbc-art-images:catalog-source 4.17 compliance-operator + ``` + +3. **Generate CatalogSource for ServiceMesh on OCP 4.19**: + ``` + /fbc-art-images:catalog-source 4.19 servicemeshoperator + ``` + +## Arguments +- $1: OCP version in X.Y format (e.g., "4.20", "4.19") +- $2: Operator name (e.g., "vertical-pod-autoscaler", "compliance-operator") + +## See Also +- `/fbc-art-images:setup` - Complete setup (CatalogSource + IDMS) +- `/fbc-art-images:idms` - Generate IDMS manifest +- `pull-secret.md` - Instructions for configuring the pull-secret prerequisite diff --git a/plugins/fbc-art-images/commands/idms.md b/plugins/fbc-art-images/commands/idms.md new file mode 100644 index 0000000..3bbb843 --- /dev/null +++ b/plugins/fbc-art-images/commands/idms.md @@ -0,0 +1,153 @@ +--- +description: Generate IDMS manifest so that art-image-share mirrors would be used on the cluster for all operator related images +argument-hint: +--- + +## Name +fbc-art-images:idms + +## Synopsis +``` +/fbc-art-images:idms +``` + +## Description +The `fbc-art-images:idms` command generates an ImageDigestMirrorSet (IDMS) manifest for configuring registry mirroring to the art-image-share registry. This allows the cluster to pull operator images from the internal Red Hat art-image-share registry. + +The IDMS configures mirroring for any related images referenced in the operator bundle to use mirror quay.io/redhat-user-workloads/ocp-art-tenant/art-images-share. + +**Note**: Applying an IDMS may trigger MachineConfig updates which will cause cluster nodes to restart sequentially. + +## Implementation + +### Step 1: Validate Inputs +- Verify `$1` (ocp-version) is provided and follows the format `X.Y` (e.g., "4.20") +- Verify `$2` (operator-name) is provided and is a valid operator name + +### Step 2: Generate IDMS Manifest +- Invoke the **generate-idms** skill with the provided OCP version and operator name +- See detailed implementation: `plugins/fbc-art-images/skills/generate-idms/SKILL.md` +- The skill will: + - Validate that `oras` and `jq` CLIs are installed + - Detect oras version to use correct JSON field (`.manifests` vs `.referrers`) + - Create the working directory (`.work/fbc-art-images/_/`) + - Discover related images from the FBC artifact using oras + - Generate the IDMS manifest at `idms.yaml` + - Generate `related-images-list.txt` with discovered images + +### Step 3: Check for Existing IDMS +- Check if an IDMS with the same name already exists: + ```bash + oc get imagedigestmirrorset art-image-share-- -o name 2>/dev/null + ``` +- If it exists, warn the user: + ``` + Warning: An IDMS named 'art-image-share--' already exists on the cluster. + + You can: + 1. Skip applying (use existing IDMS) + 2. Replace existing IDMS + 3. View existing IDMS configuration + ``` + +### Step 4: Display Manifest to User +- Show the generated manifest content +- Display the file path: `.work/fbc-art-images/_/idms.yaml` +- Show discovered images from `related-images-list.txt` +- Warn about node restarts: + ``` + IDMS manifest generated at: + .work/fbc-art-images/_/idms.yaml + + Discovered related images for + + WARNING: Applying this IDMS will trigger MachineConfig updates. + Cluster nodes will restart sequentially, which may take 20-30 minutes. + + Apply this manifest now? [y/n] + ``` + +### Step 5: Apply Manifest (if requested) +- If user confirms, apply the manifest: + ```bash + oc apply -f .work/fbc-art-images/_/idms.yaml + ``` +- Monitor MachineConfigPool status: + ```bash + oc get mcp + ``` +- Display guidance: + ``` + IDMS applied successfully! + + Monitor MachineConfigPool updates: + oc get mcp + + Watch for nodes updating: + oc get nodes + + The cluster will automatically update nodes in a rolling fashion. + This typically takes 20-30 minutes for a standard cluster. + ``` + +### Error Handling +- **Invalid OCP version**: Show error and supported format (X.Y) +- **Missing operator name**: Prompt user to provide operator name +- **oras not installed**: Guide user to install from https://oras.land/docs/installation +- **jq not installed**: Guide user to install jq +- **oras discover fails**: Check network connectivity, image URL, and quay.io access +- **No related images found**: The FBC image may not have attached artifacts or may be for a different OCP version +- **No cluster access**: Guide user to run `oc login` +- **IDMS already exists**: Provide options to view, replace, or skip +- **Apply failure**: Show error details and suggest manual review +- **MCP errors**: Guide user to check MachineConfigPool and node status + +## Return Value +- **Success**: Displays manifest location and optionally applies it +- **Files created**: + - `.work/fbc-art-images/_/idms.yaml` - IDMS manifest + - `.work/fbc-art-images/_/related-images-list.txt` - List of discovered images + - `.work/fbc-art-images/_/related-images.json` - Raw related images data (from oras) + +## Examples + +1. **Generate IDMS for AMQ Broker operator on OCP 4.20**: + ``` + /fbc-art-images:idms 4.20 amq-broker-rhel9 + ``` + Output: + ``` + IDMS manifest generated at: + .work/fbc-art-images/4.20_amq-broker-rhel9/idms.yaml + + WARNING: Applying this IDMS will trigger MachineConfig updates. + Apply this manifest now? [y/n] + ``` + +2. **Generate IDMS for Advanced Cluster Management on OCP 4.19**: + ``` + /fbc-art-images:idms 4.19 advanced-cluster-management + ``` + +3. **Generate IDMS for Kubernetes NMState operator on OCP 4.18**: + ``` + /fbc-art-images:idms 4.18 kubernetes-nmstate-rhel9-operator + ``` + +## Arguments +- $1: OCP version in X.Y format (e.g., "4.20", "4.19") +- $2: Operator name (e.g., "amq-broker-rhel9", "advanced-cluster-management", "kubernetes-nmstate-rhel9-operator") + +## Notes +- **Prerequisites**: This command requires the `oras` CLI to be installed. Install from https://oras.land/docs/installation +- The IDMS is operator and version-specific, named: `art-image-share--` +- Each operator/version combination gets its own IDMS to avoid conflicts +- The IDMS only mirrors images discovered from the specific FBC image +- MachineConfigPool updates happen automatically after applying IDMS +- Nodes restart one at a time to minimize cluster disruption +- The related images are pulled from Konflux-attached artifacts on the FBC image + +## See Also +- `/fbc-art-images:setup` - Complete setup (CatalogSource + IDMS) +- `/fbc-art-images:catalog-source` - Generate CatalogSource manifest +- `pull-secret.md` - Instructions for configuring the pull-secret prerequisite diff --git a/plugins/fbc-art-images/commands/setup.md b/plugins/fbc-art-images/commands/setup.md new file mode 100644 index 0000000..ea637c2 --- /dev/null +++ b/plugins/fbc-art-images/commands/setup.md @@ -0,0 +1,165 @@ +--- +description: Generate CatalogSource, IDMS, and configure pull-secret for FBC testing +argument-hint: +--- + +## Name +fbc-art-images:setup + +## Synopsis +``` +/fbc-art-images:setup +``` + +## Description +The `fbc-art-images:setup` command automates the setup process for testing operators built in FBC (File-Based Catalog) by Konflux. It generates all necessary Kubernetes manifests and updates the cluster configuration to enable testing with art-image-share registry images. + +This command orchestrates two key operations: +1. Creates a CatalogSource manifest pointing to the FBC image +2. Generates an IDMS (ImageDigestMirrorSet) manifest for registry mirroring + +**Prerequisites**: The cluster pull-secret must be configured with art-image-share credentials before running this command. See `pull-secret.md` in the plugin directory for detailed instructions. + +The command is designed to streamline the workflow for OpenShift engineers testing operator releases. + +## Implementation + +### Step 1: Validate Inputs and Prerequisites +- Verify `$1` (ocp-version) is provided and follows the format `X.Y` (e.g., "4.18") +- Verify `$2` (operator-name) is provided and is a valid operator name +- Confirm the user has cluster access by checking `oc whoami` +- **Check pull-secret prerequisite**: Verify that the cluster's `pull-secret` contains a token that allows pulling images from `quay.io/redhat-user-workloads/ocp-art-tenant/art-images-share` + - If it doesn't exist, show error: + ``` + Error: Pull-secret doesn't have auth credentials for `quay.io/redhat-user-workloads/ocp-art-tenant/art-images-share` + Before using this plugin, you must configure the art-image-share pull-secret. + See pull-secret.md in the plugin directory for detailed instructions. + ``` + - Exit pull-secret verification doesn't contain that token +- Check if `oras` CLI is installed: + ```bash + which oras + ``` +- If `oras` not installed, guide the user to install it from https://oras.land/docs/installation +- Check if `jq` is installed: + ```bash + which jq + ``` + +### Step 2: Generate CatalogSource Manifest +- Invoke the **generate-catalog-source** skill with the provided OCP version and operator name +- See detailed implementation: `plugins/fbc-art-images/skills/generate-catalog-source/SKILL.md` +- The skill will: + - Construct the FBC image URL + - Create the working directory (`.work/fbc-art-images/_/`) + - Generate the CatalogSource manifest at `catalogsource.yaml` + +### Step 3: Generate IDMS Manifest +- Invoke the **generate-idms** skill with the provided OCP version and operator name +- See detailed implementation: `plugins/fbc-art-images/skills/generate-idms/SKILL.md` +- The skill will: + - Validate that `oras` and `jq` CLIs are installed + - Detect oras version to use correct JSON field (`.manifests` vs `.referrers`) + - Discover related images from the FBC artifact using oras + - Generate the IDMS manifest at `idms.yaml` + - Generate `related-images-list.txt` with discovered images +- Display discovered images to user + +### Step 4: Verify Pull-Secret +- Fetch the current pull-secret from the cluster: + ```bash + oc get secret/pull-secret -n openshift-config -o jsonpath='{.data.\.dockerconfigjson}' | base64 -d > .work/fbc-art-images/pull-secret.json + ``` +- Check if quay.io/redhat-user-workloads/ocp-art-tenant/art-images-share credentials already exist in the pull-secret +- If credentials don't exist, prompt the user: + ``` + To access quay.io/redhat-user-workloads/ocp-art-tenant/art-images-share repository, you need to add credentials to the pull-secret. +``` + Display instructions from pull-secret.md + +### Step 5: Present Manifests to User +- Display the generated manifests to the user +- Show file locations: + - `.work/fbc-art-images/_/catalogsource.yaml` + - `.work/fbc-art-images/_/idms.yaml` + - `.work/fbc-art-images/pull-secret.yaml` +- Ask the user if they want to apply the manifests: + ``` + Generated manifests are ready. Would you like to: + 1. Apply all manifests now + 2. Review manifests before applying + 3. Only generate (don't apply) + ``` + +### Step 6: Apply Manifests (if requested) +- If user chooses to apply, execute: + ```bash + oc apply -f .work/fbc-art-images/pull-secret.yaml + oc apply -f .work/fbc-art-images/_/idms.yaml + oc apply -f .work/fbc-art-images/_/catalogsource.yaml + ``` +- Wait for CatalogSource to be ready: + ```bash + oc wait --for=condition=Ready catalogsource/test---catalog -n openshift-marketplace --timeout=5m + ``` +- Display success message with next steps: + ``` + Setup complete! The CatalogSource is ready. + + Next steps: + 1. Check available operators: oc get packagemanifests -n openshift-marketplace + 2. Create a Subscription to install your operator + 3. Monitor MachineConfig updates (IDMS may trigger node restarts) + ``` + +### Error Handling +- **No cluster access**: Prompt user to login with `oc login` +- **Invalid OCP version**: Show supported format (X.Y) +- **Missing pull-secret prerequisite**: Display configuration instructions from `pull-secret.md` +- **CatalogSource generation errors**: See detailed error handling in `plugins/fbc-art-images/skills/generate-catalog-source/SKILL.md` +- **IDMS generation errors**: See detailed error handling in `plugins/fbc-art-images/skills/generate-idms/SKILL.md` + - Includes: oras/jq not installed, oras version differences, discovery failures, no related images found +- **Failed manifest apply**: Show error and suggest manual application +- **CatalogSource not ready**: Show troubleshooting tips (check image pull, check logs, verify pull-secret) + +## Return Value +- **Success**: Displays manifest locations and application status +- **Files created**: + - `.work/fbc-art-images/_/catalogsource.yaml` + - `.work/fbc-art-images/_/idms.yaml` + - `.work/fbc-art-images/_/related-images-list.txt` (discovered images) + - `.work/fbc-art-images/_/related-images.json` (raw oras data) + +## Examples + +1. **Basic usage for OpenShift 4.20 with AMQ Broker operator**: + ``` + /fbc-art-images:setup 4.20 amq-broker-rhel9 + ``` + Output: + ``` + Generated manifests for amq-broker-rhel9 on OCP 4.20: + - CatalogSource: .work/fbc-art-images/4.20_amq-broker-rhel9/catalogsource.yaml + - IDMS: .work/fbc-art-images/4.20_amq-broker-rhel9/idms.yaml + + Apply manifests? [y/n] + ``` + +2. **Setup for OCP 4.19 with Advanced Cluster Management**: + ``` + /fbc-art-images:setup 4.19 advanced-cluster-management + ``` + +3. **Setup for OCP 4.18 with Kubernetes NMState operator**: + ``` + /fbc-art-images:setup 4.18 kubernetes-nmstate-rhel9-operator + ``` + +## Arguments +- $1: OCP version in X.Y format (e.g., "4.20", "4.19") +- $2: Operator name (e.g., "amq-broker-rhel9", "advanced-cluster-management", "kubernetes-nmstate-rhel9-operator") + +## See Also +- `/fbc-art-images:catalog-source` - Generate only CatalogSource manifest +- `/fbc-art-images:idms` - Generate only IDMS manifest +- `pull-secret.md` - Instructions for configuring the pull-secret prerequisite diff --git a/plugins/fbc-art-images/how-to-update-pull-secret.md b/plugins/fbc-art-images/how-to-update-pull-secret.md new file mode 100644 index 0000000..4766c1d --- /dev/null +++ b/plugins/fbc-art-images/how-to-update-pull-secret.md @@ -0,0 +1,91 @@ +# How to update the pull-secret with the token for art-images-share + + +## Description +This file provides instructions on how to update the OpenShift cluster's pull-secret to include credentials for pulling images from mirror `quay.io/redhat-user-workloads/ocp-art-tenant/art-images-share`. + +Overall, the user fetches the current pull-secret, adds or updates the art-image-share credentials, and applies the updated secret to the cluster. + +This is a cluster-scoped configuration that only needs to be done once per cluster, regardless of which operators you're testing. + +**Note**: Updating the pull-secret may trigger a cluster-wide update as nodes refresh their credentials. + +## Prerequisites + +### Obtaining art-image-share Pull Secret + +Before running this command, you must obtain the art-image-share pull secret from BitWarden: + +1. **Request access to BitWarden collection**: + - Your rover ID must be added to the rover group: https://rover.redhat.com/groups/group/art-images-share + - Request access from the ART team on #forum-ocp-art + - Provide your rover ID when requesting access + +2. **Download the pull secret from BitWarden**: + - Access the BitWarden collection "Art Images Share" + - Download the pull secret file + - Save it (for instance) to: `.work/fbc-art-images/art-images-share-pull-secret` + - Verify it's a valid JSON file with Docker registry credentials + +3. **Validate Environment** +- Verify cluster access: `oc whoami` +- Check if user has permissions to access secrets in openshift-config namespace + + +## Step 1: Fetch Current Pull-Secret +- Retrieve the current pull-secret from the cluster: + ```bash + oc get secret/pull-secret -n openshift-config -o jsonpath='{.data.\.dockerconfigjson}' | base64 -d > .work/fbc-art-images/pull-secret.json + ``` +- If the command fails, check if the secret exists, and if you have permissions to update cluster scope secrets + +## Step 2: Check for Existing Credentials +- Parse the pull-secret JSON to check if art-image-share credentials already exist +- Look for the key: `auths["quay.io/redhat-user-workloads/ocp-art-tenant/art-images-share"]` +- If credentials exist, you might want to verify they are still valid and skip updating the secret. + + +## Step 3: Generate Updated Pull-Secret + +- Update the pull-secret JSON structure by adding the entry for `quay.io/redhat-user-workloads/ocp-art-tenant/art-images-share` from `.work/fbc-art-images/art-images-share-pull-secret`: + ```json + { + "auths": { + "quay.io/redhat-user-workloads/ocp-art-tenant/art-images-share": { + "auth": "" + }, + ... existing auths ... + } + } + ``` +- Save the updated pull-secret to: + - `.work/fbc-art-images/pull-secret-updated.json` (JSON format) + +## Step 4: Create Kubernetes Secret Manifest +- Base64-encode the entire updated pull-secret JSON + ```bash + cat .work/fbc-art-images/pull-secret-updated.json | base64 + ``` +- Use the following template to generate a `.work/fbc-art-images/pull-secret.yaml` file: + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: pull-secret + namespace: openshift-config + type: kubernetes.io/dockerconfigjson + data: + .dockerconfigjson: + ``` + +## Step 5: Verify access to art-images-share +- Test image pull (any image, below an example): + ```bash + podman pull --authfile .work/fbc-art-images/pull-secret-updated.json quay.io/redhat-user-workloads/ocp-art-tenant/art-images-share@sha256:cb6baf5ddd055d99e406d6cee9921833cca16c0fa6ff0d5880df1c30e44e2f7e + ``` + +## Step 6: Apply Updated Pull-Secret +- Apply the manifest to update the `pull-secret` on the cluster: + ```bash + oc apply -f .work/fbc-art-images/pull-secret.yaml + ``` diff --git a/plugins/fbc-art-images/skills/generate-catalog-source/SKILL.md b/plugins/fbc-art-images/skills/generate-catalog-source/SKILL.md new file mode 100644 index 0000000..c219a82 --- /dev/null +++ b/plugins/fbc-art-images/skills/generate-catalog-source/SKILL.md @@ -0,0 +1,235 @@ +--- +name: Generate CatalogSource Manifest +description: Generate a CatalogSource manifest for FBC operator testing +--- + +# Generate CatalogSource Manifest + +This skill provides detailed implementation guidance for generating a CatalogSource manifest that points to FBC (File-Based Catalog) images built in Konflux. + +## When to Use This Skill + +Use this skill when you need to: +- Generate a CatalogSource manifest for an operator built in Konflux +- Create a manifest that makes operators available in the cluster's OperatorHub +- Implement the CatalogSource generation step in commands like `/fbc-art-images:catalog-source` or `/fbc-art-images:setup` + +## Prerequisites + +- **OCP version**: Must be in `X.Y` format (e.g., "4.20", "4.19") +- **Operator name**: Valid operator name (e.g., "amq-broker-rhel9", "advanced-cluster-management") + +## Implementation Steps + +### Step 1: Construct FBC Image URL + +The FBC image URL follows a specific pattern in the art-fbc repository: + +``` +quay.io/redhat-user-workloads/ocp-art-tenant/art-fbc:ocp____ +``` + +**Pattern breakdown:** +- **Registry**: `quay.io/redhat-user-workloads/ocp-art-tenant/art-fbc` +- **Tag format**: `ocp____` (note the double underscores) + +**Example:** +- OCP version: `4.20` +- Operator: `advanced-cluster-management` +- Resulting URL: `quay.io/redhat-user-workloads/ocp-art-tenant/art-fbc:ocp__4.20__advanced-cluster-management` + +### Step 2: Create Working Directory + +Create a directory for storing generated manifests: + +```bash +mkdir -p .work/fbc-art-images/_/ +``` + +**Notes:** +- Use underscore `_` to separate OCP version and operator name in directory name +- If the directory already exists, don't error (it's safe to reuse) +- This directory will contain all generated manifests for this operator/version combination + +### Step 3: Generate CatalogSource YAML + +Create the manifest file at: +``` +.work/fbc-art-images/_/catalogsource.yaml +``` + +**Template:** +```yaml +apiVersion: operators.coreos.com/v1alpha1 +kind: CatalogSource +metadata: + name: test---catalog + namespace: openshift-marketplace +spec: + sourceType: grpc + image: + displayName: Catalog (FBC) + publisher: Red Hat + updateStrategy: + registryPoll: + interval: 10m +``` + +**Field descriptions:** +- **name**: Format is `test---catalog` (use hyphens between components) +- **namespace**: Always `openshift-marketplace` (where CatalogSources are deployed) +- **sourceType**: Always `grpc` for FBC images +- **image**: The FBC image URL constructed in Step 1 +- **displayName**: Human-readable name shown in OperatorHub UI +- **publisher**: Always "Red Hat" for these operators +- **updateStrategy.registryPoll.interval**: Check for updates every 10 minutes + +**Example manifest** (for amq-broker-rhel9 on OCP 4.20): +```yaml +apiVersion: operators.coreos.com/v1alpha1 +kind: CatalogSource +metadata: + name: test-4.20-amq-broker-rhel9-catalog + namespace: openshift-marketplace +spec: + sourceType: grpc + image: quay.io/redhat-user-workloads/ocp-art-tenant/art-fbc:ocp__4.20__amq-broker-rhel9 + displayName: amq-broker-rhel9 Catalog (FBC) + publisher: Red Hat + updateStrategy: + registryPoll: + interval: 10m +``` + +### Step 4: Return Manifest Location + +Return the path to the generated manifest: +``` +.work/fbc-art-images/_/catalogsource.yaml +``` + +## Error Handling + +### Invalid OCP Version Format +If the OCP version doesn't match `X.Y` format: +``` +Error: Invalid OCP version format: '' +Expected format: X.Y (e.g., "4.20", "4.19", "4.18") +``` + +### Missing Operator Name +If operator name is empty or not provided: +``` +Error: Operator name is required +Example operator names: "amq-broker-rhel9", "advanced-cluster-management", "kubernetes-nmstate-rhel9-operator" +``` + +### Working Directory Creation Failure +If unable to create the working directory: +``` +Error: Failed to create working directory: .work/fbc-art-images/_/ +Check filesystem permissions and available disk space. +``` + +### File Write Failure +If unable to write the manifest file: +``` +Error: Failed to write CatalogSource manifest to: .work/fbc-art-images/_/catalogsource.yaml +Check filesystem permissions and available disk space. +``` + +## Examples + +### Example 1: AMQ Broker on OCP 4.20 +**Input:** +- OCP version: `4.20` +- Operator name: `amq-broker-rhel9` + +**Generated file:** `.work/fbc-art-images/4.20_amq-broker-rhel9/catalogsource.yaml` + +**Content:** +```yaml +apiVersion: operators.coreos.com/v1alpha1 +kind: CatalogSource +metadata: + name: test-4.20-amq-broker-rhel9-catalog + namespace: openshift-marketplace +spec: + sourceType: grpc + image: quay.io/redhat-user-workloads/ocp-art-tenant/art-fbc:ocp__4.20__amq-broker-rhel9 + displayName: amq-broker-rhel9 Catalog (FBC) + publisher: Red Hat + updateStrategy: + registryPoll: + interval: 10m +``` + +### Example 2: Advanced Cluster Management on OCP 4.19 +**Input:** +- OCP version: `4.19` +- Operator name: `advanced-cluster-management` + +**Generated file:** `.work/fbc-art-images/4.19_advanced-cluster-management/catalogsource.yaml` + +**Content:** +```yaml +apiVersion: operators.coreos.com/v1alpha1 +kind: CatalogSource +metadata: + name: test-4.19-advanced-cluster-management-catalog + namespace: openshift-marketplace +spec: + sourceType: grpc + image: quay.io/redhat-user-workloads/ocp-art-tenant/art-fbc:ocp__4.19__advanced-cluster-management + displayName: advanced-cluster-management Catalog (FBC) + publisher: Red Hat + updateStrategy: + registryPoll: + interval: 10m +``` + +### Example 3: Kubernetes NMState on OCP 4.18 +**Input:** +- OCP version: `4.18` +- Operator name: `kubernetes-nmstate-rhel9-operator` + +**Generated file:** `.work/fbc-art-images/4.18_kubernetes-nmstate-rhel9-operator/catalogsource.yaml` + +**Content:** +```yaml +apiVersion: operators.coreos.com/v1alpha1 +kind: CatalogSource +metadata: + name: test-4.18-kubernetes-nmstate-rhel9-operator-catalog + namespace: openshift-marketplace +spec: + sourceType: grpc + image: quay.io/redhat-user-workloads/ocp-art-tenant/art-fbc:ocp__4.18__kubernetes-nmstate-rhel9-operator + displayName: kubernetes-nmstate-rhel9-operator Catalog (FBC) + publisher: Red Hat + updateStrategy: + registryPoll: + interval: 10m +``` + +## Output Format + +The skill should return: +- **File path**: Absolute or relative path to the generated manifest +- **Success message**: Confirmation that the manifest was created +- **Manifest content**: Display the generated YAML for user review + +## Notes + +- The CatalogSource name uses hyphens to separate components: `test---catalog` +- The working directory uses underscore: `_` +- The FBC image tag uses double underscores: `ocp____` +- All CatalogSources are deployed to the `openshift-marketplace` namespace +- The `grpc` sourceType is required for FBC-based catalogs +- The 10-minute poll interval ensures the catalog stays up-to-date with registry changes + +## See Also + +- Related skill: `generate-idms` - Generate IDMS manifests for registry mirroring +- Command: `/fbc-art-images:catalog-source` - User-facing command that uses this skill +- Command: `/fbc-art-images:setup` - Orchestrates both CatalogSource and IDMS generation diff --git a/plugins/fbc-art-images/skills/generate-idms/SKILL.md b/plugins/fbc-art-images/skills/generate-idms/SKILL.md new file mode 100644 index 0000000..8a54083 --- /dev/null +++ b/plugins/fbc-art-images/skills/generate-idms/SKILL.md @@ -0,0 +1,439 @@ +--- +name: Generate IDMS Manifest +description: Generate an ImageDigestMirrorSet manifest for art-image-share registry mirroring +--- + +# Generate IDMS Manifest + +This skill provides detailed implementation guidance for generating an ImageDigestMirrorSet (IDMS) manifest that configures registry mirroring to the art-image-share registry for operator images. + +## When to Use This Skill + +Use this skill when you need to: +- Generate an IDMS manifest for operator image mirroring +- Configure the cluster to pull operator images from art-image-share registry +- Discover related images from FBC artifacts built in Konflux +- Implement the IDMS generation step in commands like `/fbc-art-images:idms` or `/fbc-art-images:setup` + +## Prerequisites + +- **OCP version**: Must be in `X.Y` format (e.g., "4.20", "4.19") +- **Operator name**: Valid operator name (e.g., "amq-broker-rhel9", "advanced-cluster-management") +- **oras CLI**: Required for discovering related images from FBC artifacts + - Installation: https://oras.land/docs/installation + - Check: `which oras` +- **jq CLI**: Required for parsing JSON output from oras + - Check: `which jq` + +## Implementation Steps + +### Step 1: Validate Prerequisites + +**Check for oras CLI:** +```bash +which oras +``` + +If not installed, show installation instructions: +``` +Error: oras CLI is not installed + +Install oras from: https://oras.land/docs/installation + +Quick install options: +- macOS: brew install oras +- Linux: Download from https://github.com/oras-project/oras/releases +``` + +**Check for jq CLI:** +```bash +which jq +``` + +If not installed: +``` +Error: jq CLI is not installed + +Install jq: +- macOS: brew install jq +- Linux: sudo apt-get install jq (Debian/Ubuntu) or sudo yum install jq (RHEL/CentOS) +``` + +**Detect oras version:** +```bash +oras version +``` + +Parse the output to determine if version is >= 1.3.0 or < 1.3.0. This determines which JSON field to use (`.referrers` vs `.manifests`). + +### Step 2: Create Working Directory + +Create a directory for storing discovered images and manifests: + +```bash +mkdir -p .work/fbc-art-images/_/ +cd .work/fbc-art-images/_/ +``` + +**Notes:** +- Use underscore `_` to separate OCP version and operator name +- If the directory already exists, that's fine (reuse it) +- Change into this directory to run oras commands + +### Step 3: Construct FBC Image URL + +The FBC image URL follows the same pattern as CatalogSource: + +``` +quay.io/redhat-user-workloads/ocp-art-tenant/art-fbc:ocp____ +``` + +**Example:** +- OCP version: `4.20` +- Operator: `amq-broker-rhel9` +- URL: `quay.io/redhat-user-workloads/ocp-art-tenant/art-fbc:ocp__4.20__amq-broker-rhel9` + +### Step 4: Discover Related Images + +Use oras to discover and extract related images from the FBC artifact. The command differs based on oras version. + +**For oras version < 1.3.0:** +```bash +cd .work/fbc-art-images/_/ +oras discover --format json quay.io/redhat-user-workloads/ocp-art-tenant/art-fbc:ocp____ | \ + jq -r '.manifests[] | select(.artifactType == "application/vnd.konflux-ci.attached-artifact") | .digest' | \ + xargs -I {} oras pull quay.io/redhat-user-workloads/ocp-art-tenant/art-fbc@{} && \ + cat related-images.json | jq -r '.[]' | sed 's/@sha256:.*//' > related-images-list.txt +``` + +**For oras version >= 1.3.0:** +```bash +cd .work/fbc-art-images/_/ +oras discover --format json quay.io/redhat-user-workloads/ocp-art-tenant/art-fbc:ocp____ | \ + jq -r '.referrers[] | select(.artifactType == "application/vnd.konflux-ci.attached-artifact") | .digest' | \ + xargs -I {} oras pull quay.io/redhat-user-workloads/ocp-art-tenant/art-fbc@{} && \ + cat related-images.json | jq -r '.[]' | sed 's/@sha256:.*//' > related-images-list.txt +``` + +**Command breakdown:** +1. `oras discover`: Finds artifacts attached to the FBC image +2. `jq -r '.manifests[]'` or `jq -r '.referrers[]'`: Extracts manifests/referrers from JSON (version-dependent) +3. `select(.artifactType == "application/vnd.konflux-ci.attached-artifact")`: Filters for Konflux artifacts +4. `.digest`: Extracts the digest of the artifact +5. `xargs -I {} oras pull`: Pulls the artifact by digest (creates `related-images.json`) +6. `cat related-images.json | jq -r '.[]'`: Extracts image references from the artifact +7. `sed 's/@sha256:.*//'`: Removes digest suffixes, leaving only image repositories + +**Output files:** +- `related-images.json`: Raw JSON artifact containing all related image references +- `related-images-list.txt`: Clean list of image repositories (one per line, no digests) + +**Example `related-images-list.txt` content:** +``` +registry.redhat.io/amq-broker-7/amq-broker-rhel8-operator +registry.redhat.io/amq-broker-7/amq-broker-init-rhel8 +registry.redhat.io/amq-broker-7/amq-broker-rhel8 +``` + +### Step 5: Display Discovered Images + +Read the `related-images-list.txt` file and show the user what was discovered: + +```bash +wc -l related-images-list.txt # Count images +cat related-images-list.txt # Display list +``` + +Example output: +``` +Discovered 3 related images for amq-broker-rhel9 (OCP 4.20): + - registry.redhat.io/amq-broker-7/amq-broker-rhel8-operator + - registry.redhat.io/amq-broker-7/amq-broker-init-rhel8 + - registry.redhat.io/amq-broker-7/amq-broker-rhel8 +``` + +### Step 6: Generate IDMS YAML + +Create the manifest file at: +``` +.work/fbc-art-images/_/idms.yaml +``` + +**Template structure:** +```yaml +apiVersion: config.openshift.io/v1 +kind: ImageDigestMirrorSet +metadata: + name: art-image-share-- +spec: + imageDigestMirrors: + - mirrors: + - quay.io/redhat-user-workloads/ocp-art-tenant/art-images-share + source: + - mirrors: + - quay.io/redhat-user-workloads/ocp-art-tenant/art-images-share + source: + # ... repeat for each image in related-images-list.txt +``` + +**Generation logic:** +1. Read `related-images-list.txt` line by line +2. For each line (image source), create an `imageDigestMirrors` entry +3. Each entry has: + - `mirrors`: Always `["quay.io/redhat-user-workloads/ocp-art-tenant/art-images-share"]` + - `source`: The image repository from related-images-list.txt + +**Example manifest** (for amq-broker-rhel9 on OCP 4.20): +```yaml +apiVersion: config.openshift.io/v1 +kind: ImageDigestMirrorSet +metadata: + name: art-image-share-4.20-amq-broker-rhel9 +spec: + imageDigestMirrors: + - mirrors: + - quay.io/redhat-user-workloads/ocp-art-tenant/art-images-share + source: registry.redhat.io/amq-broker-7/amq-broker-rhel8-operator + - mirrors: + - quay.io/redhat-user-workloads/ocp-art-tenant/art-images-share + source: registry.redhat.io/amq-broker-7/amq-broker-init-rhel8 + - mirrors: + - quay.io/redhat-user-workloads/ocp-art-tenant/art-images-share + source: registry.redhat.io/amq-broker-7/amq-broker-rhel8 +``` + +### Step 7: Return Manifest Location + +Return the paths to the generated files: +- IDMS manifest: `.work/fbc-art-images/_/idms.yaml` +- Related images list: `.work/fbc-art-images/_/related-images-list.txt` +- Raw JSON artifact: `.work/fbc-art-images/_/related-images.json` + +## Error Handling + +### oras CLI Not Installed +``` +Error: oras CLI is not installed + +Install oras from: https://oras.land/docs/installation + +Quick install options: +- macOS: brew install oras +- Linux: Download from https://github.com/oras-project/oras/releases +``` + +### jq CLI Not Installed +``` +Error: jq CLI is not installed + +Install jq: +- macOS: brew install jq +- Linux: sudo apt-get install jq (Debian/Ubuntu) or sudo yum install jq (RHEL/CentOS) +``` + +### oras discover Fails +If `oras discover` returns an error: +``` +Error: Failed to discover related images for FBC image: +quay.io/redhat-user-workloads/ocp-art-tenant/art-fbc:ocp____ + +Possible causes: +1. Network connectivity issues +2. Invalid FBC image tag (check OCP version and operator name) +3. Image doesn't exist in the registry +4. Authentication required (check quay.io credentials) + +Try verifying the image exists: +oras manifest fetch quay.io/redhat-user-workloads/ocp-art-tenant/art-fbc:ocp____ +``` + +### No Related Images Found +If `related-images-list.txt` is empty or doesn't exist: +``` +Error: No related images found for this operator + +Possible causes: +1. The FBC image doesn't have attached Konflux artifacts +2. The artifact format has changed +3. Wrong oras version (try >= 1.3.0 and use .referrers instead of .manifests) + +The FBC image may not be built with Konflux CI, or the related-images artifact is missing. +``` + +### related-images.json Not Found +If `oras pull` doesn't create `related-images.json`: +``` +Error: related-images.json not found after pulling artifact + +Possible causes: +1. The artifact doesn't contain a related-images.json file +2. The artifact format has changed +3. Konflux CI build didn't attach the related images + +Check what files were pulled: +ls -la .work/fbc-art-images/_/ +``` + +### Invalid Image Format in related-images.json +If jq parsing fails or produces unexpected output: +``` +Error: Failed to parse related-images.json + +The artifact format may have changed. Expected JSON array of image strings. + +Check the file content: +cat .work/fbc-art-images/_/related-images.json +``` + +### Working Directory Creation Failure +``` +Error: Failed to create working directory: .work/fbc-art-images/_/ +Check filesystem permissions and available disk space. +``` + +### File Write Failure +``` +Error: Failed to write IDMS manifest to: .work/fbc-art-images/_/idms.yaml +Check filesystem permissions and available disk space. +``` + +## Examples + +### Example 1: AMQ Broker on OCP 4.20 + +**Input:** +- OCP version: `4.20` +- Operator name: `amq-broker-rhel9` + +**Commands executed:** +```bash +mkdir -p .work/fbc-art-images/4.20_amq-broker-rhel9/ +cd .work/fbc-art-images/4.20_amq-broker-rhel9/ + +# Assuming oras >= 1.3.0 +oras discover --format json quay.io/redhat-user-workloads/ocp-art-tenant/art-fbc:ocp__4.20__amq-broker-rhel9 | \ + jq -r '.referrers[] | select(.artifactType == "application/vnd.konflux-ci.attached-artifact") | .digest' | \ + xargs -I {} oras pull quay.io/redhat-user-workloads/ocp-art-tenant/art-fbc@{} && \ + cat related-images.json | jq -r '.[]' | sed 's/@sha256:.*//' > related-images-list.txt +``` + +**Generated `related-images-list.txt`:** +``` +registry.redhat.io/amq-broker-7/amq-broker-rhel8-operator +registry.redhat.io/amq-broker-7/amq-broker-init-rhel8 +registry.redhat.io/amq-broker-7/amq-broker-rhel8 +``` + +**Generated `idms.yaml`:** +```yaml +apiVersion: config.openshift.io/v1 +kind: ImageDigestMirrorSet +metadata: + name: art-image-share-4.20-amq-broker-rhel9 +spec: + imageDigestMirrors: + - mirrors: + - quay.io/redhat-user-workloads/ocp-art-tenant/art-images-share + source: registry.redhat.io/amq-broker-7/amq-broker-rhel8-operator + - mirrors: + - quay.io/redhat-user-workloads/ocp-art-tenant/art-images-share + source: registry.redhat.io/amq-broker-7/amq-broker-init-rhel8 + - mirrors: + - quay.io/redhat-user-workloads/ocp-art-tenant/art-images-share + source: registry.redhat.io/amq-broker-7/amq-broker-rhel8 +``` + +### Example 2: Advanced Cluster Management on OCP 4.19 + +**Input:** +- OCP version: `4.19` +- Operator name: `advanced-cluster-management` + +**Generated files:** +- `.work/fbc-art-images/4.19_advanced-cluster-management/idms.yaml` +- `.work/fbc-art-images/4.19_advanced-cluster-management/related-images-list.txt` +- `.work/fbc-art-images/4.19_advanced-cluster-management/related-images.json` + +**Generated `idms.yaml`:** +```yaml +apiVersion: config.openshift.io/v1 +kind: ImageDigestMirrorSet +metadata: + name: art-image-share-4.19-advanced-cluster-management +spec: + imageDigestMirrors: + # ... entries for each discovered ACM image +``` + +### Example 3: Handling oras Version Differences + +**oras version 1.2.0 (older):** +```bash +oras discover --format json | jq -r '.manifests[]...' +``` + +**oras version 1.3.0+ (newer):** +```bash +oras discover --format json | jq -r '.referrers[]...' +``` + +**Version detection logic:** +```bash +oras_version=$(oras version | grep -oP 'Version:\s+\K[0-9.]+') +if [[ $(echo "$oras_version 1.3.0" | tr " " "\n" | sort -V | head -n1) == "1.3.0" ]]; then + # Use .referrers + json_field=".referrers" +else + # Use .manifests + json_field=".manifests" +fi +``` + +## Output Format + +The skill should return: +- **IDMS manifest path**: Path to the generated IDMS YAML file +- **Related images count**: Number of images discovered +- **Related images list**: Display of discovered images for user review +- **Success message**: Confirmation that manifests were created + +## Important Notes + +### IDMS Impact on Cluster +- Applying an IDMS triggers MachineConfig updates +- Cluster nodes will restart sequentially (rolling restart) +- The restart process typically takes 20-30 minutes for a standard cluster +- Nodes are updated one at a time to minimize disruption + +### Image Format Details +- Related images in `related-images.json` include digest suffixes (`@sha256:...`) +- The IDMS `source` field requires only the repository (no digest) +- Use `sed 's/@sha256:.*//'` to strip digests from image references +- Example transformation: + - Input: `registry.redhat.io/amq-broker-7/amq-broker-rhel8@sha256:abc123...` + - Output: `registry.redhat.io/amq-broker-7/amq-broker-rhel8` + +### IDMS Naming Convention +- Format: `art-image-share--` +- Use hyphens between all components +- Each operator/version combination gets its own IDMS to avoid conflicts +- Example: `art-image-share-4.20-amq-broker-rhel9` + +### Mirror Configuration +- All operator images mirror to: `quay.io/redhat-user-workloads/ocp-art-tenant/art-images-share` +- This is a single shared mirror repository for all art-images-share content +- The cluster will attempt to pull from the mirror first before falling back to the source + +### oras CLI Version Considerations +- The JSON structure changed in oras 1.3.0 +- Older versions use `.manifests[]` to access discovered artifacts +- Newer versions use `.referrers[]` to access discovered artifacts +- Always detect the version and use the appropriate field + +## See Also + +- Related skill: `generate-catalog-source` - Generate CatalogSource manifests +- Command: `/fbc-art-images:idms` - User-facing command that uses this skill +- Command: `/fbc-art-images:setup` - Orchestrates both CatalogSource and IDMS generation +- oras documentation: https://oras.land/docs/ +- Konflux CI: https://konflux-ci.dev/