add /operator-catalog plugin to build operator index image

Author: Xia-Zhao-rh

PLUGINS.md

@@ -123,6 +123,7 @@ OLM (Operator Lifecycle Manager) plugin for operator management and debugging
 - **`/olm:diagnose` `[operator-name] [namespace] [--fix] [--cluster]`** - Diagnose and optionally fix common OLM and operator issues
 - **`/olm:install` `<operator-name> [namespace] [channel] [source] [--approval=Automatic|Manual]`** - Install a day-2 operator using Operator Lifecycle Manager
 - **`/olm:list` `[namespace] [--all-namespaces]`** - List installed operators in the cluster
+- **`/olm:opm` `<action> [arguments...]`** - Execute opm (Operator Package Manager) commands for building and managing operator catalogs
 - **`/olm:search` `[query] [--catalog <catalog-name>]`** - Search for available operators in catalog sources
 - **`/olm:status` `<operator-name> [namespace]`** - Get detailed status and health information for an operator
 - **`/olm:uninstall` `<operator-name> [namespace] [--remove-crds] [--remove-namespace]`** - Uninstall a day-2 operator and optionally remove its resources

docs/data.json

@@ -328,6 +328,12 @@
           "synopsis": "/olm:list [namespace] [--all-namespaces]",
           "argument_hint": "[namespace] [--all-namespaces]"
         },
+        {
+          "name": "opm",
+          "description": "Execute opm (Operator Package Manager) commands for building and managing operator catalogs",
+          "synopsis": "/olm:opm build-index-image <catalog-path> <index-image-tag> [--cacheless] [--arch=<arch>] [--base-image=<image>] [--builder-image=<image>]",
+          "argument_hint": "<action> [arguments...]"
+        },
         {
           "name": "search",
           "description": "Search for available operators in catalog sources",

plugins/olm/commands/opm.md

@@ -0,0 +1,359 @@
+---
+description: Execute opm (Operator Package Manager) commands for building and managing operator catalogs
+argument-hint: <action> [arguments...]
+---
+
+## Name
+olm:opm
+
+## Synopsis
+```
+/olm:opm build-index-image <catalog-path> <index-image-tag> [--cacheless] [--arch=<arch>] [--base-image=<image>] [--builder-image=<image>]
+/olm:opm build-semver-index-image <semver-template-file> <index-image-tag> [--cacheless] [--arch=<arch>] [--base-image=<image>] [--builder-image=<image>]
+/olm:opm generate-semver-template <bundle-list> [--output=<file>] [--major=true|false] [--minor=true|false]
+/olm:opm list packages <index-ref>
+/olm:opm list channels <index-ref> [package-name]
+/olm:opm list bundles <index-ref> [package-name]
+```
+
+## Description
+The `olm:opm` command provides a unified interface to `opm` (Operator Package Manager) operations for building and managing operator catalog indexes. It supports building catalog indexes, generating semver templates, and querying catalog contents.
+
+## Arguments
+- `$1`: **action** - The action to perform:
+  - `build-index-image`: Build an index from an existing catalog directory
+  - `build-semver-index-image`: Build an index from a semver template
+  - `generate-semver-template`: Generate a semver template file
+  - `list`: List catalog contents (requires second argument: `packages`, `channels`, or `bundles`)
+- `$2+`: Additional arguments specific to each action (see Actions section below)
+
+## Actions
+
+### build-index-image
+Build an operator catalog index image from an existing catalog directory.
+
+**Synopsis:**
+```
+/olm:opm build-index-image <catalog-path> <index-image-tag> [--cacheless] [--arch=<arch>] [--base-image=<image>] [--builder-image=<image>]
+```
+
+**Arguments:**
+- `$2`: **catalog-path** - Path to the catalog directory containing the index configuration
+- `$3`: **index-image-tag** - Full image tag for the resulting index image (e.g., `quay.io/myorg/mycatalog:v1.0.0`)
+- `--cacheless`: Optional flag to build a cacheless image (uses `scratch` as base image; `--base-image` and `--builder-image` are ignored when this is set)
+- `--arch=<arch>`: Optional architecture specification (default: `multi` for multi-arch build; can specify single arch like `amd64`, `arm64`, `ppc64le`, `s390x`)
+- `--base-image=<image>`: Optional base image for the index (default: `quay.io/operator-framework/opm:latest`; ignored if `--cacheless` is set)
+- `--builder-image=<image>`: Optional builder image (default: `quay.io/operator-framework/opm:latest`; ignored if `--cacheless` is set)
+
+**Examples:**
+```
+/olm:opm build-index-image catalog quay.io/myorg/mycatalog:v1.0.0
+/olm:opm build-index-image catalog quay.io/myorg/mycatalog:v1.0.0 --cacheless
+/olm:opm build-index-image catalog quay.io/myorg/mycatalog:v1.0.0 --arch=amd64
+```
+
+### build-semver-index-image
+Build a multi-architecture operator catalog index image using the semver template format.
+
+**Synopsis:**
+```
+/olm:opm build-semver-index-image <semver-template-file> <index-image-tag> [--cacheless] [--arch=<arch>] [--base-image=<image>] [--builder-image=<image>]
+```
+
+**Arguments:**
+- `$2`: **semver-template-file** - Path to the semver template configuration file (e.g., `catalog-config.yaml`)
+- `$3`: **index-image-tag** - Full image tag for the resulting index image (e.g., `quay.io/myorg/mycatalog:v1.0.0`)
+- `--cacheless`: Optional flag to build a cacheless image (uses `scratch` as base image; `--base-image` and `--builder-image` are ignored when this is set)
+- `--arch=<arch>`: Optional architecture specification (default: `multi` for multi-arch build; can specify single arch like `amd64`, `arm64`, `ppc64le`, `s390x`)
+- `--base-image=<image>`: Optional base image for the index (default: `quay.io/operator-framework/opm:latest`; ignored if `--cacheless` is set)
+- `--builder-image=<image>`: Optional builder image (default: `quay.io/operator-framework/opm:latest`; ignored if `--cacheless` is set)
+
+**Examples:**
+```
+/olm:opm build-semver-index-image catalog-config.yaml quay.io/myorg/mycatalog:v1.0.0
+/olm:opm build-semver-index-image catalog-config.yaml quay.io/myorg/mycatalog:v1.0.0 --cacheless
+/olm:opm build-semver-index-image catalog-config.yaml quay.io/myorg/mycatalog:v1.0.0 --arch=amd64
+/olm:opm build-semver-index-image catalog-config.yaml quay.io/myorg/mycatalog:v1.0.0 --arch=multi
+```
+
+### generate-semver-template
+Generate a semver template configuration file for building operator catalogs.
+
+**Synopsis:**
+```
+/olm:opm generate-semver-template <bundle-list> [--output=<file>] [--major=true|false] [--minor=true|false]
+```
+
+**Arguments:**
+- `$2`: **bundle-list** - Comma-separated list of bundle image references (e.g., `quay.io/org/bundle:v1.0.0,quay.io/org/bundle:v1.0.1`)
+- `--output=<file>`: Optional output file path (default: `catalog-semver-config.yaml` in current directory)
+- `--major=true|false`: Optional flag to generate major version channels (default: `true`)
+- `--minor=true|false`: Optional flag to generate minor version channels (default: `false`)
+
+**Examples:**
+```
+/olm:opm generate-semver-template quay.io/org/bundle:v1.0.0,quay.io/org/bundle:v1.0.1
+/olm:opm generate-semver-template quay.io/org/bundle:v1.0.0,quay.io/org/bundle:v1.0.1 --output=my-catalog.yaml
+/olm:opm generate-semver-template quay.io/org/bundle:v1.0.0,quay.io/org/bundle:v1.1.0 --minor=true
+```
+
+### list packages
+List all operator packages available in a catalog index.
+
+**Synopsis:**
+```
+/olm:opm list packages <index-ref>
+```
+
+**Arguments:**
+- `$2`: **list** - Must be "list"
+- `$3`: **packages** - Must be "packages"
+- `$4`: **index-ref** - Catalog index reference, either:
+  - Image tag: `quay.io/myorg/mycatalog:v1.0.0`
+  - Directory path: `./catalog` or `/path/to/catalog`
+
+**Examples:**
+```
+/olm:opm list packages quay.io/olmqe/nginx8518-index-test:v1
+/olm:opm list packages ./catalog
+```
+
+### list channels
+List channels for operator packages in a catalog index.
+
+**Synopsis:**
+```
+/olm:opm list channels <index-ref> [package-name]
+```
+
+**Arguments:**
+- `$2`: **list** - Must be "list"
+- `$3`: **channels** - Must be "channels"
+- `$4`: **index-ref** - Catalog index reference (image tag or directory path)
+- `$5`: **package-name** (Optional) - Name of a specific package to list channels for
+
+**Examples:**
+```
+/olm:opm list channels quay.io/olmqe/nginx8518-index-test:v1
+/olm:opm list channels quay.io/olmqe/nginx8518-index-test:v1 nginx85187
+/olm:opm list channels ./catalog
+```
+
+### list bundles
+List bundles for operator packages in a catalog index.
+
+**Synopsis:**
+```
+/olm:opm list bundles <index-ref> [package-name]
+```
+
+**Arguments:**
+- `$2`: **list** - Must be "list"
+- `$3`: **bundles** - Must be "bundles"
+- `$4`: **index-ref** - Catalog index reference (image tag or directory path)
+- `$5`: **package-name** (Optional) - Name of a specific package to list bundles for
+
+**Examples:**
+```
+/olm:opm list bundles quay.io/olmqe/nginx8518-index-test:v1
+/olm:opm list bundles quay.io/olmqe/nginx8518-index-test:v1 nginx85187
+/olm:opm list bundles ./catalog
+```
+
+## Implementation
+
+### Step 1: Parse Action
+- Extract the action from `$1`
+- Validate the action is one of: `build-index-image`, `build-semver-index-image`, `generate-semver-template`, `list`
+- If invalid action, display error with available actions
+
+### Step 2: Check Prerequisites
+Verify required tools are installed:
+- Check for `opm`: `which opm`
+  - If not found, provide installation instructions: https://github.com/operator-framework/operator-registry/releases
+- For build actions, also check for `podman`: `which podman`
+  - If not found, provide installation instructions based on user's platform
+
+### Step 3: Route to Action Handler
+Based on the action, call the appropriate implementation:
+
+#### For `build-index-image`:
+1. **Parse Arguments and Set Defaults**
+   - Extract catalog path from `$2`
+   - Extract index image tag from `$3`
+   - Parse optional flags: `--cacheless`, `--arch`, `--base-image`, `--builder-image`
+   - Set defaults: arch=`multi`, base-image=`quay.io/operator-framework/opm:latest`, builder-image=`quay.io/operator-framework/opm:latest`
+
+2. **Verify Catalog Directory**
+   - Check catalog directory exists: `test -d <catalog-path>`
+
+3. **Validate Catalog**
+   ```bash
+   opm validate <catalog-path>
+   ```
+
+4. **Generate Dockerfile**
+   - If cacheless: `opm generate dockerfile <catalog-path> --base-image=scratch`
+   - If normal: `opm generate dockerfile <catalog-path> -b <builder-image> -i <base-image>`
+
+5. **Determine Build Platform**
+   - If arch=`multi`: `linux/amd64,linux/arm64,linux/ppc64le,linux/s390x`
+   - Otherwise: `linux/<arch>`
+
+6. **Create Podman Manifest**
+   ```bash
+   podman manifest rm <index-image-tag> 2>/dev/null || true
+   podman manifest create <index-image-tag>
+   ```
+
+7. **Build Image**
+   ```bash
+   podman build --platform <platform-list> --manifest <index-image-tag> . -f catalog.Dockerfile
+   ```
+
+8. **Push Manifest**
+   ```bash
+   podman manifest push <index-image-tag>
+   ```
+
+9. **List Bundles in Index**
+   ```bash
+   opm alpha list bundles <index-image-tag>
+   ```
+
+10. **Display Success Message**
+
+#### For `build-semver-index-image`:
+1. **Parse Arguments and Set Defaults**
+   - Extract semver template file from `$2`
+   - Extract index image tag from `$3`
+   - Parse optional flags: `--cacheless`, `--arch`, `--base-image`, `--builder-image`
+   - Set defaults: arch=`multi`, base-image=`quay.io/operator-framework/opm:latest`, builder-image=`quay.io/operator-framework/opm:latest`
+
+2. **Verify Template File**
+   - Check file exists: `test -f <semver-template-file>`
+
+3. **Create Catalog and Render Template**
+   ```bash
+   mkdir -p catalog
+   opm alpha render-template semver <semver-template-file> -o yaml > catalog/index.yaml
+   ```
+
+4. **Validate Catalog**
+   ```bash
+   opm validate catalog
+   ```
+
+5. **Generate Dockerfile**
+   - If cacheless: `opm generate dockerfile catalog --base-image=scratch`
+   - If normal: `opm generate dockerfile catalog -b <builder-image> -i <base-image>`
+
+6. **Determine Build Platform**
+   - If arch=`multi`: `linux/amd64,linux/arm64,linux/ppc64le,linux/s390x`
+   - Otherwise: `linux/<arch>`
+
+7. **Create Podman Manifest**
+   ```bash
+   podman manifest rm <index-image-tag> 2>/dev/null || true
+   podman manifest create <index-image-tag>
+   ```
+
+8. **Build Image**
+   ```bash
+   podman build --platform <platform-list> --manifest <index-image-tag> . -f catalog.Dockerfile
+   ```
+
+9. **Push Manifest**
+   ```bash
+   podman manifest push <index-image-tag>
+   ```
+
+10. **List Bundles in Index**
+   ```bash
+   opm alpha list bundles <index-image-tag>
+   ```
+
+11. **Display Success Message**
+
+#### For `generate-semver-template`:
+1. **Parse Arguments and Set Defaults**
+   - Extract bundle list from `$2`
+   - Parse optional flags: `--output`, `--major`, `--minor`
+   - Set defaults: output=`catalog-semver-config.yaml`, major=`true`, minor=`false`
+
+2. **Validate Bundle List**
+   - Split by commas
+   - Validate each bundle is a valid image reference
+
+3. **Generate YAML Content**
+   ```yaml
+   Schema: olm.semver
+   GenerateMajorChannels: <major-value>
+   GenerateMinorChannels: <minor-value>
+   Candidate:
+     Bundles:
+     - Image: <bundle-1>
+     - Image: <bundle-2>
+   ```
+
+4. **Write Template File**
+   - Check if file exists and confirm overwrite if needed
+   - Write YAML content
+
+5. **Validate Generated File**
+   - Read back and verify YAML is well-formed
+
+6. **Display Success Message**
+   - Show file path, bundles included, settings
+   - Suggest next step: `/olm:opm build-semver-index-image <output-file> <image-tag>`
+
+#### For `list`:
+1. **Parse List Type**
+   - Extract list type from `$2` (must be `packages`, `channels`, or `bundles`)
+   - If invalid, display error with available types
+
+2. **Parse Index Reference and Optional Package**
+   - Extract index-ref from `$3`
+   - Extract optional package-name from `$4` (for channels and bundles)
+
+3. **Determine Reference Type**
+   - Check if directory: `test -d <index-ref>`
+
+4. **Execute List Command**
+   - For packages: `opm alpha list packages <index-ref>`
+   - For channels: `opm alpha list channels <index-ref> [package-name]`
+   - For bundles: `opm alpha list bundles <index-ref> [package-name]`
+
+5. **Display Results**
+   - Show the output with appropriate formatting
+   - Display count of items found
+
+## Return Value
+
+**Format**: Varies by action
+
+- **build-index-image / build-semver-index-image**: Success message with image tag, architectures, and bundle list
+- **generate-semver-template**: Success message with file path and configuration details
+- **list**: Table or list of catalog contents
+
+On failure, displays:
+- Clear error message indicating which step/action failed
+- Relevant tool output for debugging
+- Suggestions for resolution
+
+## Notes
+
+- Ensure you are authenticated to container registries before building/pushing images (use `podman login`)
+- For build operations, the `catalog.Dockerfile` is created in the current working directory
+- Multi-architecture builds can be time-consuming
+- Cacheless builds result in smaller images and use `scratch` as the base image
+- When using `--cacheless`, the `--base-image` and `--builder-image` options are ignored (scratch is always used as base)
+- Index references can be either image tags or local directory paths
+- Bundle images must be accessible from where you build the catalog
+- Image tags should include the full registry hostname (e.g., `quay.io/org/image:tag` not `quay/org/image:tag`)
+
+## Related Commands
+
+- `/olm:install` - Install an operator using OLM
+- `/olm:catalog` - Manage catalog sources
+- `/olm:debug` - Debug OLM issues