openshift-eng · sherine-k · Oct 27, 2025
diff --git 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
@@ -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
@@ -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 <ocp-version> <operator-name>
+```
+
+**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/<ocp-version>_<operator-name>/catalogsource.yaml`
+- `.work/fbc-art-images/<ocp-version>_<operator-name>/idms.yaml`
+
+---
+
+### `/fbc-art-images:catalog-source`
+
+Generate only the CatalogSource manifest.
+
+**Usage:**
+```
+/fbc-art-images:catalog-source <ocp-version> <operator-name>
+```
+
+**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__<version>__<operator>`
+
+---
+
+### `/fbc-art-images:idms`
+
+Generate only the IDMS manifest for registry mirroring.
+
+**Usage:**
+```
+/fbc-art-images:idms <ocp-version> <operator-name>
+```
+
+**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-<ocp-version>-<operator-name>`
+
+**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 <operator-name>
+   ```
+
+2. **Create a Subscription to install the operator:**
+   ```yaml
+   apiVersion: operators.coreos.com/v1alpha1
+   kind: Subscription
+   metadata:
+     name: <operator-name>
+     namespace: openshift-operators
+   spec:
+     channel: stable
+     name: <operator-package-name>
+     source: <operator-name>-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 <operator-name>-catalog -n openshift-marketplace -o yaml
+
+# Check catalog pod logs
+oc logs -n openshift-marketplace -l olm.catalogSource=<operator-name>-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-<ocp-version>-<operator-name> -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 <node-name>
+```
+
+## 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__<version>__<operator-name>
+```
+
+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/
+├── <ocp-version>_<operator-name>/
+│   ├── 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
@@ -0,0 +1,106 @@
+---
+description: Generate CatalogSource manifest for testing operators built in Konflux
+argument-hint: <ocp-version> <operator-name>
+---
+
+## Name
+fbc-art-images:catalog-source
+
+## Synopsis
+```
+/fbc-art-images:catalog-source <ocp-version> <operator-name>
+```
+
+## 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/<ocp-version>_<operator-name>/`)
+  - 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/<ocp-version>_<operator-name>/catalogsource.yaml`
+- Ask if the user wants to apply the manifest:
+  ```
+  CatalogSource manifest generated at:
+  .work/fbc-art-images/<ocp-version>_<operator-name>/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/<ocp-version>_<operator-name>/catalogsource.yaml
+  ```
+- Wait for the CatalogSource to become ready:
+  ```bash
+  oc wait --for=condition=Ready catalogsource/test-<ocp-version>-<operator-name>-catalog -n openshift-marketplace --timeout=5m
+  ```
+- Display success message:
+  ```
+  CatalogSource applied successfully!
+
+  Check the status:
+  oc get catalogsource test-<ocp-version>-<operator-name>-catalog -n openshift-marketplace
+
+  View available operators:
+  oc get packagemanifests -n openshift-marketplace | grep test-<ocp-version>-<operator-name>-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/<ocp-version>_<operator-name>/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