#Upgrading Alauda DevOps Connectors Operator

This document provides instructions for upgrading the Alauda DevOps Connectors 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 resources.

#Upgrade Overview

Upgrading the Alauda DevOps Connectors Operator allows you to access new features, bug fixes, and improvements to its components. The Alauda DevOps Connectors Operator handles the upgrade of all components according to your configuration.

#Before You Begin

Before upgrading the Alauda DevOps Connectors 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 Connector components configurations are compatible with the new version
• Confirm that all current components are in a ready state

#Migration to ConnectorsConfig

Earlier Connectors releases required administrators to create each component CR (ConnectorsCore, ConnectorsGit, …) directly. Starting from the release that ships ConnectorsConfig, a single cluster-wide ConnectorsConfig replaces them all. When such a cluster upgrades, the operator absorbs every existing standalone CR into a new ConnectorsConfig and deletes the originals — automatically, with no manual step. If the source cluster never had standalone component CRs, this section does not apply.

kubectl get connectorscore,connectorsgit,connectorsgithub,connectorsgitlab,\
connectorsoci,connectorsharbor,connectorsk8s,connectorsmaven,connectorsnpm,\
connectorspypi,connectorssonarqube,connectorsnexus,connectorsjfrog \
  -A -o yaml > connectors-standalone-backup.yaml

#Pre-upgrade Decisions

The migration runs automatically and cannot be paused. Review the following before the operator upgrade rolls out:

• Target namespace. The new ConnectorsConfig lands in the namespace of your existing ConnectorsCore, or in the operator's install namespace if no ConnectorsCore exists. See Auto-creation namespace priority for the full rule.
• Cross-namespace consolidation. If standalone CRs span multiple namespaces, every managed child consolidates into the ConnectorsCore namespace: originals are deleted, managed children are re-created there. Confirm your standalone-CR layout matches the intended post-upgrade topology.

#Verifying the Migration

After the operator upgrade reports Succeeded, watch the new ConnectorsConfig:

kubectl get connectorsconfig -A
kubectl describe connectorsconfig connectors-config -n <namespace>

A BootstrapCompleted event marks the migration finished, and status.conditions[Ready]=True indicates every component has re-converged. While the operator is still cleaning up the original standalone CRs you may briefly see components in the Migrating phase — this is a benign transient state, distinct from Failed.

If a component stays in Failed, the cause is almost always a stale standalone CR the bootstrap could not delete. Follow A Component Is Stuck in Failed for the diagnostic and recovery steps.

#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 Connectors Operator

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

3. View Available Versions

   • On the Alauda DevOps Connectors 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 Connectors 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 connectors-operator namespace:

     $ kubectl get pods -n connectors-operator
     When all pods are in Running state, the operator upgrade is complete. The operator will then reconcile ConnectorsConfig and upgrade every managed component (ConnectorsCore, ConnectorsGit, ConnectorsOCI, etc.) automatically.
   • Check the components upgrade status:

     $ kubectl get connectorsconfig -A
     $ kubectl describe connectorsconfig connectors-config -n <namespace>
     When status.conditions[Ready]=True is reported on the ConnectorsConfig, every managed component has finished re-converging.

8. Verify the Upgrade

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

     $ kubectl get csv -n connectors-operator
     
     NAME                         DISPLAY                    VERSION   REPLACES                     PHASE
     connectors-operator.v1.y.z   Alauda DevOps Connectors   1.y.z     connectors-operator.v1.y.z   Succeeded
     When the VERSION matches the new version, the upgrade is complete.
   • Verify that all Connector components are functioning correctly

#Post-Upgrade Steps

After the upgrade completes successfully:

1. Verify Component Status

   • Check the ConnectorsConfig roll-up status to confirm every managed component has converged on the new version:

     kubectl get connectorsconfig -A
     kubectl describe connectorsconfig connectors-config -n <namespace>
     For the meaning of each per-component phase, see Status & Phases.

2. Test Functionality

   • Run a job using connector csi or deploy an app pulling the image through oci connector 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

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

• Pipeline Integration resources fail to render after upgrade — your Tekton release may be older than the schema-version the operator ships. Cap the installed schema-version on the pipeline-integration install flag.

• Check the Alauda DevOps Connectors Operator pod logs:

  $ kubectl logs -l control-plane=connectors-operator -n connectors-operator

• Verify the status of the ConnectorsConfig to identify which component is failing:

  $ kubectl get connectorsconfig -A
  $ kubectl describe connectorsconfig connectors-config -n <namespace>

  status.components.<name>.message points at the failing component. If a component stays in Failed, follow A Component Is Stuck in Failed for the diagnostic and recovery steps.

#Next Steps

After successfully upgrading the Alauda DevOps Connectors Operator:

• Explore new features introduced in the latest version
• Consider enabling additional components that may be available in the new version