Initial commit
This commit is contained in:
Zhongwei Li
433
commands/catalog.md
Normal file
433
commands/catalog.md
Normal file
@@ -0,0 +1,433 @@
|
||||
---
|
||||
description: Manage catalog sources for discovering and installing operators
|
||||
argument-hint: <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**:
|
||||
```bash
|
||||
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**:
|
||||
```bash
|
||||
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**:
|
||||
```yaml
|
||||
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**:
|
||||
```bash
|
||||
oc apply -f /tmp/catalogsource-{name}.yaml
|
||||
```
|
||||
|
||||
5. **Wait for CatalogSource to be Ready**:
|
||||
```bash
|
||||
oc wait --for=condition=READY catalogsource/{name} -n {namespace} --timeout=300s
|
||||
```
|
||||
|
||||
6. **Verify Pod is Running**:
|
||||
```bash
|
||||
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**:
|
||||
```bash
|
||||
oc get catalogsource {name} -n {namespace} --ignore-not-found
|
||||
```
|
||||
|
||||
3. **Check for Operators Using This Catalog**:
|
||||
```bash
|
||||
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**:
|
||||
```bash
|
||||
oc delete catalogsource {name} -n {namespace}
|
||||
```
|
||||
|
||||
6. **Wait for Pod to be Deleted**:
|
||||
```bash
|
||||
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**:
|
||||
```bash
|
||||
oc get catalogsource {name} -n {namespace} -o json
|
||||
```
|
||||
|
||||
3. **Trigger Refresh by Deleting Pod**:
|
||||
```bash
|
||||
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**:
|
||||
```bash
|
||||
oc wait --for=condition=Ready pod -l olm.catalogSource={name} -n {namespace} --timeout=300s
|
||||
```
|
||||
|
||||
5. **Verify Catalog is Updated**:
|
||||
```bash
|
||||
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**:
|
||||
```bash
|
||||
oc get catalogsource {name} -n {namespace} -o json
|
||||
```
|
||||
|
||||
3. **Get Pod Details**:
|
||||
```bash
|
||||
oc get pods -n {namespace} -l olm.catalogSource={name} -o json
|
||||
```
|
||||
|
||||
4. **Get Recent Events**:
|
||||
```bash
|
||||
oc get events -n {namespace} --field-selector involvedObject.name={name} --sort-by='.lastTimestamp'
|
||||
```
|
||||
|
||||
5. **Count Available Operators**:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
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**:
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
# Force refresh
|
||||
/olm:catalog refresh {catalog-name}
|
||||
```
|
||||
|
||||
- **Connection failures**:
|
||||
```bash
|
||||
# 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](https://olm.operatorframework.io/docs/tasks/creating-catalog-from-index/)
|
||||
- [Operator Lifecycle Manager Documentation](https://olm.operatorframework.io/)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user