350 lines
12 KiB
Markdown
350 lines
12 KiB
Markdown
---
|
|
description: Update an operator to the latest version or switch channels
|
|
argument-hint: <operator-name> [namespace] [--channel=<channel>] [--approve]
|
|
---
|
|
|
|
## Name
|
|
olm:upgrade
|
|
|
|
## Synopsis
|
|
```
|
|
/olm:upgrade <operator-name> [namespace] [--channel=<channel>] [--approve]
|
|
```
|
|
|
|
## Description
|
|
The `olm:upgrade` command updates an installed operator to the latest version in its current channel or switches to a different channel. It can also approve pending InstallPlans for operators with manual approval mode.
|
|
|
|
This command helps you:
|
|
- Update operators to the latest version in their channel
|
|
- Switch operators to different channels (e.g., stable to tech-preview)
|
|
- Approve pending upgrade InstallPlans for manual approval mode
|
|
- Monitor upgrade progress
|
|
- Rollback on failure (if possible via OLM)
|
|
|
|
## Implementation
|
|
|
|
The command performs the following steps:
|
|
|
|
1. **Parse Arguments**:
|
|
- `$1`: Operator name (required) - Name of the operator to upgrade
|
|
- `$2`: Namespace (optional) - Namespace where operator is installed
|
|
- If not provided, searches for the operator across all namespaces
|
|
- `$3+`: Flags (optional):
|
|
- `--channel=<channel-name>`: Switch to a different channel
|
|
- `--approve`: Automatically approve pending InstallPlan (for manual approval mode)
|
|
|
|
2. **Prerequisites Check**:
|
|
- Verify `oc` CLI is installed: `which oc`
|
|
- Verify cluster access: `oc whoami`
|
|
- Check if user has sufficient privileges
|
|
|
|
3. **Locate Operator**:
|
|
- If namespace provided, verify operator exists:
|
|
```bash
|
|
oc get subscription {operator-name} -n {namespace} --ignore-not-found
|
|
```
|
|
- If no namespace provided, search across all namespaces:
|
|
```bash
|
|
oc get subscription --all-namespaces -o json | jq -r '.items[] | select(.spec.name=="{operator-name}") | .metadata.namespace'
|
|
```
|
|
- If not found, display error with suggestions
|
|
- If multiple instances found, prompt user to specify namespace
|
|
|
|
4. **Get Current State**:
|
|
- Get current Subscription:
|
|
```bash
|
|
oc get subscription {operator-name} -n {namespace} -o json
|
|
```
|
|
- Extract:
|
|
- Current channel: `.spec.channel`
|
|
- Install plan approval: `.spec.installPlanApproval`
|
|
- Installed CSV: `.status.installedCSV`
|
|
- Current CSV: `.status.currentCSV`
|
|
- Get current CSV version:
|
|
```bash
|
|
oc get csv {installed-csv} -n {namespace} -o jsonpath='{.spec.version}'
|
|
```
|
|
|
|
5. **Check for Available Updates**:
|
|
- Get PackageManifest:
|
|
```bash
|
|
oc get packagemanifest {operator-name} -n openshift-marketplace -o json
|
|
```
|
|
- Extract available channels and their latest versions
|
|
- If `--channel` flag is specified, verify channel exists
|
|
- If no channel flag, check for updates in current channel
|
|
- Compare current version with latest available version
|
|
- Reference: https://docs.redhat.com/en/documentation/openshift_container_platform/4.20/html/operators/administrator-tasks#olm-updating-operators
|
|
|
|
6. **Display Upgrade Plan**:
|
|
```
|
|
Operator Upgrade Plan:
|
|
|
|
Operator: {display-name}
|
|
Namespace: {namespace}
|
|
Current Version: {current-version}
|
|
Current Channel: {current-channel}
|
|
|
|
[If switching channels:]
|
|
Target Channel: {new-channel}
|
|
Target Version: {new-version}
|
|
|
|
[If upgrading in same channel:]
|
|
Latest Version: {latest-version} (in channel: {current-channel})
|
|
|
|
Approval Mode: {Automatic|Manual}
|
|
```
|
|
|
|
7. **Check for Pending InstallPlans** (for manual approval mode):
|
|
- Get pending InstallPlans:
|
|
```bash
|
|
oc get installplan -n {namespace} -o json | jq '.items[] | select(.spec.approved==false)'
|
|
```
|
|
- If pending InstallPlan exists and `--approve` flag is set:
|
|
- Display InstallPlan details
|
|
- Approve the InstallPlan (skip to step 9)
|
|
- If pending InstallPlan exists and no `--approve` flag:
|
|
```
|
|
⏸️ Pending InstallPlan found (requires manual approval)
|
|
|
|
InstallPlan: {installplan-name}
|
|
Target Version: {target-version}
|
|
|
|
To approve: /olm:upgrade {operator-name} {namespace} --approve
|
|
Or use: /olm:approve {operator-name} {namespace}
|
|
```
|
|
- Exit, waiting for user to approve
|
|
|
|
8. **Perform Channel Switch** (if `--channel` flag provided):
|
|
- Confirm with user (unless `--force` flag):
|
|
```
|
|
WARNING: Switching channels may upgrade or downgrade the operator.
|
|
|
|
Current: {current-channel} ({current-version})
|
|
Target: {new-channel} ({target-version})
|
|
|
|
Continue? (yes/no)
|
|
```
|
|
- Update Subscription to new channel:
|
|
```bash
|
|
oc patch subscription {operator-name} -n {namespace} \
|
|
--type merge --patch '{"spec":{"channel":"{new-channel}"}}'
|
|
```
|
|
- Display confirmation:
|
|
```
|
|
✓ Subscription updated to channel: {new-channel}
|
|
```
|
|
|
|
9. **Approve Pending InstallPlan** (if `--approve` flag or automatic approval):
|
|
- If approval mode is Manual and `--approve` flag is set:
|
|
```bash
|
|
oc patch installplan {installplan-name} -n {namespace} \
|
|
--type merge --patch '{"spec":{"approved":true}}'
|
|
```
|
|
- Display approval confirmation:
|
|
```
|
|
✓ InstallPlan approved: {installplan-name}
|
|
```
|
|
|
|
10. **Monitor Upgrade Progress**:
|
|
- Wait for new InstallPlan to be created (if switching channels):
|
|
```bash
|
|
oc get installplan -n {namespace} -w --timeout=60s
|
|
```
|
|
- Wait for new CSV to reach "Succeeded" phase:
|
|
```bash
|
|
oc get csv -n {namespace} -w --timeout=300s
|
|
```
|
|
- Display progress updates:
|
|
```
|
|
🔄 Upgrade in progress...
|
|
⏳ Waiting for InstallPlan to complete...
|
|
⏳ New CSV installing: {new-csv-name}
|
|
⏳ Old CSV replacing: {old-csv-name}
|
|
```
|
|
- Poll every 10 seconds to check status
|
|
- Timeout: 10 minutes for upgrade to complete
|
|
|
|
11. **Verify Upgrade Success**:
|
|
- Check new CSV status:
|
|
```bash
|
|
oc get csv -n {namespace} -o json
|
|
```
|
|
- Verify new CSV phase is "Succeeded"
|
|
- Get new version:
|
|
```bash
|
|
oc get csv {new-csv-name} -n {namespace} -o jsonpath='{.spec.version}'
|
|
```
|
|
- Check deployments are healthy:
|
|
```bash
|
|
oc get deployments -n {namespace}
|
|
```
|
|
- Check pods are running:
|
|
```bash
|
|
oc get pods -n {namespace}
|
|
```
|
|
|
|
12. **Display Upgrade Summary**:
|
|
```
|
|
✓ Operator Upgrade Complete!
|
|
|
|
Operator: {display-name}
|
|
Namespace: {namespace}
|
|
Previous Version: {old-version}
|
|
Current Version: {new-version}
|
|
Channel: {channel}
|
|
|
|
Deployment Status:
|
|
- {deployment-1}: 1/1 replicas ready
|
|
- {deployment-2}: 1/1 replicas ready
|
|
|
|
To check status: /olm:status {operator-name} {namespace}
|
|
```
|
|
|
|
13. **Handle Upgrade Failures**:
|
|
- If upgrade fails or times out:
|
|
```
|
|
❌ Operator upgrade failed
|
|
|
|
Current State:
|
|
- CSV: {csv-name} (Phase: {phase})
|
|
- Message: {error-message}
|
|
|
|
Troubleshooting steps:
|
|
1. Check CSV status: oc describe csv {csv-name} -n {namespace}
|
|
2. Check events: oc get events -n {namespace} --sort-by='.lastTimestamp'
|
|
3. Check InstallPlan: oc get installplan -n {namespace}
|
|
4. Run diagnostics: /olm:diagnose {operator-name} {namespace}
|
|
|
|
To rollback (if OLM supports):
|
|
oc patch subscription {operator-name} -n {namespace} \
|
|
--type merge --patch '{"spec":{"channel":"{old-channel}"}}'
|
|
```
|
|
|
|
## Return Value
|
|
- **Success**: Operator upgraded successfully with new version details
|
|
- **Pending Approval**: Upgrade waiting for manual approval with instructions
|
|
- **No Update Available**: Operator is already at the latest version
|
|
- **Error**: Upgrade failed with specific error message and troubleshooting guidance
|
|
- **Format**: Structured output showing:
|
|
- Previous and current versions
|
|
- Channel information
|
|
- Deployment and pod status
|
|
- Next steps or related commands
|
|
|
|
## Examples
|
|
|
|
1. **Check for and install updates in current channel**:
|
|
```
|
|
/olm:upgrade openshift-cert-manager-operator
|
|
```
|
|
|
|
2. **Upgrade with specific namespace**:
|
|
```
|
|
/olm:upgrade external-secrets-operator eso-operator
|
|
```
|
|
|
|
3. **Switch to a different channel**:
|
|
```
|
|
/olm:upgrade openshift-cert-manager-operator cert-manager-operator --channel=tech-preview-v1.14
|
|
```
|
|
This switches from stable-v1 to tech-preview-v1.14 channel.
|
|
|
|
4. **Approve pending upgrade (manual approval mode)**:
|
|
```
|
|
/olm:upgrade openshift-cert-manager-operator --approve
|
|
```
|
|
|
|
5. **Switch channel and approve in one command**:
|
|
```
|
|
/olm:upgrade prometheus prometheus-operator --channel=beta --approve
|
|
```
|
|
|
|
## Arguments
|
|
- **$1** (operator-name): Name of the operator to upgrade (required)
|
|
- Example: "openshift-cert-manager-operator"
|
|
- Must match the operator's Subscription name
|
|
- **$2** (namespace): Namespace where operator is installed (optional)
|
|
- If not provided, searches all namespaces
|
|
- Example: "cert-manager-operator"
|
|
- **$3+** (flags): Optional flags
|
|
- `--channel=<channel-name>`: Switch to specified channel
|
|
- Example: `--channel=stable-v1`, `--channel=tech-preview`
|
|
- Triggers upgrade/downgrade to the version in that channel
|
|
- `--approve`: Automatically approve pending InstallPlan
|
|
- Only needed for operators with Manual approval mode
|
|
- Equivalent to `/olm:approve` command
|
|
|
|
## Notes
|
|
|
|
- **Automatic Updates**: Operators with `installPlanApproval: Automatic` will upgrade automatically when new versions are available in their channel
|
|
- **Manual Approval**: Operators with `installPlanApproval: Manual` require explicit approval via `--approve` flag or `/olm:approve` command
|
|
- **Channel Switching**: Changing channels may result in upgrade or downgrade depending on the versions in each channel
|
|
- **Rollback**: OLM has limited rollback support. Switching back to the previous channel may work, but data migration issues may occur
|
|
- **Upgrade Timing**: Upgrades happen according to the operator's upgrade strategy (some may cause downtime)
|
|
|
|
## Troubleshooting
|
|
|
|
- **No updates available**:
|
|
```bash
|
|
# Check current version
|
|
oc get csv -n {namespace}
|
|
|
|
# Check available versions
|
|
oc get packagemanifest {operator-name} -n openshift-marketplace -o json
|
|
```
|
|
|
|
- **Upgrade stuck or pending**:
|
|
```bash
|
|
# Check InstallPlan status
|
|
oc get installplan -n {namespace}
|
|
|
|
# Check for events
|
|
oc get events -n {namespace} --sort-by='.lastTimestamp' | tail -20
|
|
```
|
|
|
|
- **Manual approval required**:
|
|
```bash
|
|
# List pending InstallPlans
|
|
oc get installplan -n {namespace} -o json | jq '.items[] | select(.spec.approved==false)'
|
|
|
|
# Approve specific InstallPlan
|
|
/olm:approve {operator-name} {namespace}
|
|
```
|
|
|
|
- **Upgrade failed**:
|
|
```bash
|
|
# Check CSV status
|
|
oc describe csv -n {namespace}
|
|
|
|
# Check operator logs
|
|
oc logs -n {namespace} deployment/{operator-deployment}
|
|
|
|
# Run diagnostics
|
|
/olm:diagnose {operator-name} {namespace}
|
|
```
|
|
|
|
- **Rollback needed**:
|
|
- OLM doesn't have built-in rollback
|
|
- Can try switching back to previous channel, but may have issues:
|
|
```bash
|
|
oc patch subscription {operator-name} -n {namespace} \
|
|
--type merge --patch '{"spec":{"channel":"{old-channel}"}}'
|
|
```
|
|
- Consider backup/restore of custom resources before upgrading
|
|
|
|
## Related Commands
|
|
|
|
- `/olm:status <operator-name>` - Check current version and available updates
|
|
- `/olm:approve <operator-name>` - Approve pending InstallPlans
|
|
- `/olm:install <operator-name>` - Install an operator
|
|
- `/olm:diagnose <operator-name>` - Diagnose upgrade issues
|
|
|
|
## Additional Resources
|
|
|
|
- [Red Hat OpenShift: Updating Installed Operators](https://docs.redhat.com/en/documentation/openshift_container_platform/4.20/html/operators/administrator-tasks#olm-updating-operators)
|
|
- [Red Hat OpenShift: Approving Operator Upgrades](https://docs.redhat.com/en/documentation/openshift_container_platform/4.20/html/operators/administrator-tasks#olm-approving-operator-upgrades_olm-updating-operators)
|
|
- [Operator Lifecycle Manager Documentation](https://olm.operatorframework.io/)
|
|
|
|
|