#Upgrade Alauda DevOps Pipelines Operator

This document provides instructions for upgrading the Alauda DevOps Pipelines Operator to a newer version using the Marketplace/OperatorHub interface in your cluster. The upgrade process is designed to be straightforward while ensuring minimal disruption to existing Tekton resources.

#Upgrade Overview

Upgrading the Alauda DevOps Pipelines Operator allows you to access new features, bug fixes, and improvements to the Tekton ecosystem. The Alauda DevOps Pipelines Operator handles the upgrade of all Tekton components (Pipelines, Triggers, Hub, etc.) according to your configuration.

#Before You Begin

Before upgrading the Alauda DevOps Pipelines Operator, ensure you:

• Have administrative access to your cluster
• Review the release notes for the new version to understand any breaking changes
• Verify that your existing Tekton component configurations are compatible with the new version
• Confirm that all Tekton components are in a ready state
• Upload a new version of the Operator, refer to the installation guide for operator upload instructions .

#Confirm Target Channel First

Before you approve an upgrade, confirm which channel your Subscription uses:

• stable (default): Tracks LTS releases only, recommended for production.
• latest: Tracks all releases, including non-LTS.
• pipelines-4.14: Tracks patch updates in the v4.14 LTS line only. A pipelines-x.y channel exists for every LTS version, so pipelines-4.10 still tracks the previous LTS line.

#Upgrade Process

#Using Marketplace/OperatorHub

1. Access the Marketplace/OperatorHub

   • Log in to your cluster's management console
   • Navigate to the Marketplace or OperatorHub section

2. Locate the Alauda DevOps Pipelines Operator

   • Search for Alauda DevOps Pipelines in the search bar
   • Click on the Alauda DevOps Pipelines card

3. View Available Versions

   • On the Alauda DevOps Pipelines Operator details page, you'll see information about the currently installed version
   • The interface will indicate if a newer version is available
   • You can click different Channels to view all available versions

4. Initiate the Upgrade

   • If the target version is in a different Channel, switch to the corresponding Channel in the Subscription first
   • If the current Channel has a newer version available, you will see a prompt:
     • New Version Detected
       • To upgrade only the current Operator, click Confirm to upgrade.

5. Configure Upgrade Settings (if applicable)

   • Some upgrades may present configuration options
   • In most cases, the default settings will preserve your existing configuration

6. Confirm and Start the Upgrade

   • Click Confirm to begin the process
   • Review the upgrade details and confirm your selection
   • The system will update the Alauda DevOps Pipelines Operator while maintaining your custom resources

7. Monitor the Upgrade

   • The upgrade progress will be displayed in the OperatorHub interface
   • You can also check the status in the tekton-operator namespace:

     $ kubectl get pods -n tekton-operator
     When all pods are in Running state, the operator upgrade is complete. The operator will then automatically upgrade components such as Pipelines, Triggers, Chains, etc. (and Hub, if you have enabled the built-in Tekton Hub).
   • Check the components upgrade status:

     $ kubectl get tektoninstallerset -A
     $ kubectl get pods -n tekton-pipelines
     When all components and pods are in Ready state, the components upgrade is complete.

8. Verify the Upgrade

   • Check that the Alauda DevOps Pipelines Operator version has been updated:

     $ kubectl get csv -n tekton-operator
     
     NAME                        DISPLAY                   VERSION   REPLACES   PHASE
     tektoncd-operator.v4.x.x    Alauda DevOps Pipelines   4.x.x     x          Succeeded
     When the VERSION matches the new version, the upgrade is complete.
   • Verify that your Tekton components are functioning correctly
     • Test that your pipelines can run successfully

#Using kubectl CLI

You can also upgrade the Alauda DevOps Pipelines Operator using the command line interface. This method is useful for automation or when you prefer CLI-based operations.

1. Check Current Subscription

   • First, identify the current subscription and its channel:

     $ kubectl get subscriptions.operators.coreos.com -A | grep tektoncd-operator
     
     NAMESPACE               NAME                    PACKAGE                 SOURCE     CHANNEL
     tekton-operator         tektoncd-operator       tektoncd-operator       platform   stable

2. Switch to Target Channel

   • If you need to upgrade to a version in a different channel, patch the subscription:

     $ kubectl patch subscriptions.operators.coreos.com tektoncd-operator --type merge -p '{"spec":{"channel": "<target-channel>"}}' -n tekton-operator
     Replace <target-channel> with the desired channel (e.g., stable, latest, pipelines-4.14).

3. Wait for UpgradePending State

   • Monitor the subscription status until it shows UpgradePending:

     $ kubectl get subscriptions.operators.coreos.com tektoncd-operator -n tekton-operator -o yaml
     
     status:
       installplan:
         apiVersion: operators.coreos.com/v1alpha1
         kind: InstallPlan
         name: install-abc123
       state: UpgradePending
     Look for the state: UpgradePending in the output.

4. Approve the InstallPlan

   • When the subscription is in UpgradePending state, find the corresponding InstallPlan:

     $ kubectl get installplan -n tekton-operator
     
     NAME            CSV                        APPROVAL   APPROVED
     install-abc123  tektoncd-operator.v4.x.x  Manual     false

   • Approve the InstallPlan by setting the approved field to true:

     $ kubectl patch installplans.operators.coreos.com <installplan-name> --type merge -p '{"spec":{"approved":true}}' -n tekton-operator

     Replace <installplan-name> with the actual InstallPlan name from the previous step.

5. Monitor the Upgrade Progress

   • Watch the subscription status until it becomes ready:

     $ kubectl get subscriptions.operators.coreos.com tektoncd-operator -n tekton-operator -o yaml -w

   • Check the operator pods status:

     $ kubectl get pods -n tekton-operator

     Wait until all pods are in Running state.

6. Verify the Upgrade

   • Confirm the operator version has been updated:

     $ kubectl get csv -n tekton-operator
     
     NAME                        DISPLAY                   VERSION   REPLACES   PHASE
     tektoncd-operator.v4.x.x    Alauda DevOps Pipelines   4.x.x     x          Succeeded

7. Monitor Component Upgrades

   • The operator will automatically upgrade Tekton components. Monitor their progress:

     $ kubectl get tektoninstallerset -A
     $ kubectl get pods -n tekton-pipelines
     Ensure all components and pods reach Ready state.

#Post-Upgrade Steps

After the upgrade completes successfully:

1. Verify Component Status

   • Check that all Tekton components have been updated:

     kubectl get tektonconfig,tektonpipeline,tektontrigger -A
     kubectl get tektoninstallerset -A

2. Test Functionality

   • Run a simple pipeline to verify that the system is working correctly
   • Ensure that all existing integrations continue to function

3. Update Custom Resources if Needed

   • If the new version introduces changes to CRDs, you may need to update your custom resources
   • Refer to the release notes for specific migration steps

#Verify migrated TektonHub custom catalogs

If the cluster had TektonHub.spec.catalogs[] or custom CATALOGS data in the old tekton-hub-api ConfigMap, verify that the generated ArtifactHub Shim repository ConfigMap exists:

kubectl get configmap artifacthub-shim-legacy-tekton-hub-catalogs \
  -n artifacthub-shim-system \
  -o yaml

If ArtifactHub Shim is installed in a different namespace, use the namespace in TektonConfig.spec.pipeline.hub-resolver-config.artifact-hub-api. For the repository ConfigMap format and credential options, see Configure Custom Git Repositories.

Generated entries use this naming pattern:

The generated entries set optional: true. Pipeline and StepAction entries set legacyCatalogAliases: ["<catalog>"], so old hub resolver references can keep using the original catalog name while new references should use the generated canonical repository names.

If the legacy SSH Secret existed, verify the copied Secret:

kubectl get secret artifacthub-shim-legacy-tekton-hub-ssh-creds \
  -n artifacthub-shim-system

The copied Secret is normalized for ArtifactHub Shim and contains sshPrivateKey plus known_hosts. If the legacy Secret does not include known_hosts, has no private key, or has multiple private key candidates such as both id_rsa and id_ed25519, the operator leaves the migrated SSH catalog without credentialRef. The ArtifactHub Shim source will then report the Git credential problem during refresh.

The operator skips entries that conflict with existing ArtifactHub Shim repositories or aliases, and it does not overwrite a same-name ConfigMap or Secret that was not generated by this migration. Review the operator logs if an expected migrated catalog is missing.

#Rollback Procedure

If you encounter issues with the new version, you can roll back to the previous version:

1. Return to the Marketplace/OperatorHub interface
2. Select the Alauda DevOps Pipelines Operator
3. Uninstall the current version
4. Choose the previous version from the version list
5. Follow the installation process for that version

#Troubleshooting

If you encounter issues during or after the upgrade:

• Check the Alauda DevOps Pipelines Operator pod logs:

  $ kubectl logs -l name=tekton-operator -n tekton-operator

• Verify the status of your Tekton resources:

  $ kubectl get tektonconfig config -o yaml

• Ensure that all components have the expected status:

  $ kubectl get tektoninstallerset

#Next Steps

After successfully upgrading the Alauda DevOps Pipelines Operator:

• Explore new features introduced in the latest version
• Update your CI/CD pipelines to leverage new capabilities
• Consider enabling additional components that may be available in the new version