zhongwei/gh-openshift-eng-ai-helpers-plugins-olm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
gh-openshift-eng-ai-helpers…/commands/catalog.md
Zhongwei Li 07f84861a9 Initial commit
2025-11-30 08:46:11 +08:00

12 KiB
Raw Permalink Blame History

description, argument-hint
description argument-hint
Manage catalog sources for discovering and installing operators <list|add|remove|refresh|status> [arguments]

Name

olm:catalog

Synopsis

/olm:catalog list
/olm:catalog add <name> <image> [--namespace=openshift-marketplace]
/olm:catalog remove <name> [--namespace=openshift-marketplace]
/olm:catalog refresh <name> [--namespace=openshift-marketplace]
/olm:catalog status <name> [--namespace=openshift-marketplace]

Description

The olm:catalog command manages catalog sources for operator discovery and installation. Catalog sources provide the list of operators available for installation in the cluster.

This command helps you:

  • List all available catalog sources and their health status
  • Add custom or private catalog sources
  • Remove catalog sources
  • Refresh catalog sources to get latest operator updates

Implementation

Subcommand: list

  1. Get All CatalogSources:

    oc get catalogsource -n openshift-marketplace -o json

  2. Parse CatalogSource Data: For each catalog, extract:

    • Name: .metadata.name
    • Display Name: .spec.displayName
    • Publisher: .spec.publisher
    • Source Type: .spec.sourceType (grpc, configmap, etc.)
    • Image: .spec.image (for grpc type)
    • Connection State: .status.connectionState.lastObservedState
    • Last Updated: .status.connectionState.lastUpdatedTime
    • Number of Operators: Count from PackageManifests with this catalog

  3. Get Catalog Pod Status:

    oc get pods -n openshift-marketplace -l olm.catalogSource={catalog-name}

  4. Format Output:

    ═══════════════════════════════════════════════════════════
CATALOG SOURCES
═══════════════════════════════════════════════════════════

NAME                     STATUS    OPERATORS  LAST UPDATED  SOURCE TYPE
redhat-operators         READY     150        2h ago        grpc
certified-operators      READY     45         3h ago        grpc
community-operators      READY     200        1h ago        grpc
redhat-marketplace       READY     30         4h ago        grpc
custom-catalog           FAILED    0          -             grpc

═══════════════════════════════════════════════════════════
DETAILS
═══════════════════════════════════════════════════════════

redhat-operators:
  Display Name: Red Hat Operators
  Publisher: Red Hat
  Image: registry.redhat.io/redhat/redhat-operator-index:v4.20
  Pod: redhat-operators-abc123 (Running)

custom-catalog (FAILED):
  Display Name: Custom Catalog
  Publisher: My Company
  Image: registry.example.com/custom-catalog:latest
  Pod: custom-catalog-xyz789 (CrashLoopBackOff)
  Error: ImagePullBackOff

  To troubleshoot:
  /olm:catalog status custom-catalog

Subcommand: add

  1. Parse Arguments:

    • name: Catalog source name (required)
    • image: Catalog image (required)
    • --namespace: Target namespace (default: openshift-marketplace)
    • --display-name: Display name (optional)
    • --publisher: Publisher name (optional)

  2. Validate Image:

    • Check if image format is valid
    • Optionally test image accessibility (if possible)

  3. Create CatalogSource Manifest:

    apiVersion: operators.coreos.com/v1alpha1
kind: CatalogSource
metadata:
  name: {name}
  namespace: {namespace}
spec:
  sourceType: grpc
  image: {image}
  displayName: {display-name}
  publisher: {publisher}
  updateStrategy:
    registryPoll:
      interval: 30m

  4. Apply CatalogSource:

    oc apply -f /tmp/catalogsource-{name}.yaml

  5. Wait for CatalogSource to be Ready:

    oc wait --for=condition=READY catalogsource/{name} -n {namespace} --timeout=300s

  6. Verify Pod is Running:

    oc get pods -n {namespace} -l olm.catalogSource={name}

  7. Display Result:

    ✓ Catalog source added: {name}

Name: {name}
Namespace: {namespace}
Image: {image}
Status: READY
Pod: {pod-name} (Running)

To search operators: /olm:search --catalog {name}

Subcommand: remove

  1. Parse Arguments:

    • name: Catalog source name (required)
    • --namespace: Namespace (default: openshift-marketplace)

  2. Check if CatalogSource Exists:

    oc get catalogsource {name} -n {namespace} --ignore-not-found

  3. Check for Operators Using This Catalog:

    oc get subscription --all-namespaces -o json | \
  jq -r '.items[] | select(.spec.source=="{name}") | "\(.metadata.namespace)/\(.metadata.name)"'

  4. Display Warning (if operators found):

    WARNING: The following operators are using this catalog:
- namespace-1/operator-1
- namespace-2/operator-2

Removing this catalog will prevent these operators from receiving updates.

Do you want to continue? (yes/no)

  5. Delete CatalogSource:

    oc delete catalogsource {name} -n {namespace}

  6. Wait for Pod to be Deleted:

    oc wait --for=delete pod -l olm.catalogSource={name} -n {namespace} --timeout=60s

  7. Display Result:

    ✓ Catalog source removed: {name}

Subcommand: refresh

  1. Parse Arguments:

    • name: Catalog source name (required)
    • --namespace: Namespace (default: openshift-marketplace)

  2. Get Current CatalogSource:

    oc get catalogsource {name} -n {namespace} -o json

  3. Trigger Refresh by Deleting Pod:

    oc delete pod -n {namespace} -l olm.catalogSource={name}
    • This forces OLM to recreate the pod and re-fetch catalog data

  4. Wait for New Pod to be Ready:

    oc wait --for=condition=Ready pod -l olm.catalogSource={name} -n {namespace} --timeout=300s

  5. Verify Catalog is Updated:

    oc get catalogsource {name} -n {namespace} -o json | \
  jq -r '.status.connectionState.lastUpdatedTime'

  6. Display Result:

    ✓ Catalog source refreshed: {name}

Last Updated: {timestamp}
Status: READY
Pod: {pod-name} (Running)

New operators may now be available: /olm:search --catalog {name}

Subcommand: status

  1. Parse Arguments:

    • name: Catalog source name (required)
    • --namespace: Namespace (default: openshift-marketplace)

  2. Get CatalogSource Details:

    oc get catalogsource {name} -n {namespace} -o json

  3. Get Pod Details:

    oc get pods -n {namespace} -l olm.catalogSource={name} -o json

  4. Get Recent Events:

    oc get events -n {namespace} --field-selector involvedObject.name={name} --sort-by='.lastTimestamp'

  5. Count Available Operators:

    oc get packagemanifests -n openshift-marketplace -o json | \
  jq -r '.items[] | select(.status.catalogSource=="{name}") | .metadata.name' | wc -l

  6. Verify Catalog Connectivity:

    • Check if catalog is serving content by verifying PackageManifest count > 0
    • If count is 0 but pod is Running, indicates connectivity or catalog index issues
    • Review catalog pod logs for gRPC errors, image pull issues, or index corruption: 
      oc logs -n {namespace} {catalog-pod-name}

  7. Format Comprehensive Status Report:

    ═══════════════════════════════════════════════════════════
CATALOG SOURCE STATUS: {name}
═══════════════════════════════════════════════════════════

General Information:
  Name: {name}
  Namespace: {namespace}
  Display Name: {display-name}
  Publisher: {publisher}
  Source Type: {source-type}
  Image: {image}

Connection Status:
  State: {state} (READY | CONNECTING | CONNECTION_FAILED)
  Last Updated: {timestamp}
  Last Successful: {timestamp}

Pod Status:
  Name: {pod-name}
  Status: {status} (Running | CrashLoopBackOff | ImagePullBackOff)
  Ready: {ready-containers}/{total-containers}
  Restarts: {restart-count}
  Age: {age}

Catalog Content:
  Operators Available: {count}

[If issues detected:]
⚠️  Issues Detected:
  - Pod in CrashLoopBackOff
  - Last update: 24h ago (stale)
  - Connection state: CONNECTION_FAILED

Recent Events:
  {timestamp} Warning: Failed to pull image
  {timestamp} Warning: Back-off restarting failed container

Troubleshooting Steps:
  1. Check pod logs: oc logs -n {namespace} {pod-name}
  2. Check image accessibility
  3. Refresh catalog: /olm:catalog refresh {name}
  4. Verify network connectivity (for disconnected environments)

Related Commands:
  - Refresh: /olm:catalog refresh {name}
  - List operators: /olm:search --catalog {name}

Return Value

  • list: Table of all catalog sources with status
  • add: Confirmation of added catalog with details
  • remove: Confirmation of removed catalog
  • refresh: Confirmation of refresh with updated timestamp
  • status: Comprehensive status report for specific catalog

Examples

  1. List all catalog sources:

    /olm:catalog list

  2. Add custom catalog:

    /olm:catalog add my-catalog registry.example.com/my-catalog:v1.0

  3. Add catalog with metadata:

    /olm:catalog add my-catalog registry.example.com/catalog:latest \
  --display-name="My Custom Catalog" \
  --publisher="My Company"

  4. Remove catalog:

    /olm:catalog remove my-catalog

  5. Refresh catalog to get latest operators:

    /olm:catalog refresh redhat-operators

  6. Check catalog health:

    /olm:catalog status custom-catalog

  7. Add catalog for disconnected environment:

    /olm:catalog add disconnected-operators \
  mirror-registry.local:5000/olm/redhat-operators:v4.20 \
  --namespace=openshift-marketplace

Arguments

list

No arguments required.

add

  • name (required): Name for the catalog source
  • image (required): Container image containing the catalog
  • --namespace: Target namespace (default: openshift-marketplace)
  • --display-name: Human-readable display name
  • --publisher: Publisher/organization name

remove

  • name (required): Name of the catalog source to remove
  • --namespace: Namespace (default: openshift-marketplace)

refresh

  • name (required): Name of the catalog source to refresh
  • --namespace: Namespace (default: openshift-marketplace)

status

  • name (required): Name of the catalog source to check
  • --namespace: Namespace (default: openshift-marketplace)

Troubleshooting

  • Catalog pod failing:

    # Check pod logs
oc logs -n openshift-marketplace {catalog-pod-name}

# Check image pull issues
oc describe pod -n openshift-marketplace {catalog-pod-name}

  • No operators showing up:

    # Verify catalog is ready
/olm:catalog status {catalog-name}

# Check PackageManifests
oc get packagemanifests -n openshift-marketplace

  • Image pull errors (disconnected environment):

    • Verify image registry is accessible
    • Check pull secrets are configured
    • Ensure image has been mirrored correctly

  • Stale catalog data:

    # Force refresh
/olm:catalog refresh {catalog-name}

  • Connection failures:

    # Check catalog source definition
oc get catalogsource {catalog-name} -n openshift-marketplace -o yaml

# Run cluster diagnostics
/olm:diagnose --cluster

Related Commands

  • /olm:search - Search for operators in catalogs
  • /olm:install - Install operators from catalogs
  • /olm:diagnose - Diagnose catalog health issues

Additional Resources

Reference in New Issue View Git Blame Copy Permalink