gh-openshift-eng-ai-helpers-plugins-olm/commands/upgrade.md

description, argument-hint

description	argument-hint
Update an operator to the latest version or switch channels	<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:

     oc get subscription {operator-name} -n {namespace} --ignore-not-found
     

   • If no namespace provided, search across all namespaces:

     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:

     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:

     oc get csv {installed-csv} -n {namespace} -o jsonpath='{.spec.version}'
     

5. Check for Available Updates:

   • Get PackageManifest:

     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:

     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:

     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:

     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):

      oc get installplan -n {namespace} -w --timeout=60s
      

    • Wait for new CSV to reach "Succeeded" phase:

      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:

      oc get csv -n {namespace} -o json
      

    • Verify new CSV phase is "Succeeded"
    • Get new version:

      oc get csv {new-csv-name} -n {namespace} -o jsonpath='{.spec.version}'
      

    • Check deployments are healthy:

      oc get deployments -n {namespace}
      

    • Check pods are running:

      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:

  # 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:

  # Check InstallPlan status
  oc get installplan -n {namespace}
  
  # Check for events
  oc get events -n {namespace} --sort-by='.lastTimestamp' | tail -20
  

• Manual approval required:

  # 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:

  # 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:

    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
• Red Hat OpenShift: Approving Operator Upgrades
• Operator Lifecycle Manager Documentation