/catalog

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
   • Test image accessibility when the cluster has network access to the registry

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 and the ImageContentSourcePolicy or ImageDigestMirrorSet references the correct registry path

• 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

• Building Catalog Images with opm
• Operator Lifecycle Manager Documentation