Checksum in bundle descriptor makes older controllers crash during the startup process

Issue

After upgrading an operations center to version 2.401.1.3 or newer, the controllers that are not upgraded may fail to start.

In the startup log, we can see the following error traces:

SEVERE  jenkins.InitReactorRunner$1#onTaskFailed: Failed Loading bundled plugins
    com.cloudbees.jenkins.cjp.installmanager.org.yaml.snakeyaml.error.YAMLException: Unable to find property 'checksum' on class: com.cloudbees.jenkins.cjp.installmanager.casc.BundleLoader$BundleDescriptor
    at com.cloudbees.jenkins.cjp.installmanager.org.yaml.snakeyaml.introspector.PropertyUtils.getProperty(PropertyUtils.java:155)
    at com.cloudbees.jenkins.cjp.installmanager.org.yaml.snakeyaml.introspector.PropertyUtils.getProperty(PropertyUtils.java:145)
    at com.cloudbees.jenkins.cjp.installmanager.org.yaml.snakeyaml.TypeDescription.discoverProperty(TypeDescription.java:217)
    at com.cloudbees.jenkins.cjp.installmanager.org.yaml.snakeyaml.TypeDescription.getProperty(TypeDescription.java:228)
    at com.cloudbees.jenkins.cjp.installmanager.org.yaml.snakeyaml.constructor.Constructor$ConstructMapping.constructJavaBean2ndStep(Constructor.java:262)
    Caused: Cannot create property=checksum for JavaBean=com.cloudbees.jenkins.cjp.installmanager.casc.BundleLoader$BundleDescriptor@4cb43470
    in 'reader', line 1, column 1:
    apiVersion: '1'

It is caused because starting in the 2.401.1.3 release there is optional checksum field in bundle descriptors. Although the field is optional, when the bundle is sent to the controller from the operations center, that checksum is mistakenly sent in the bundle descriptor of the Effective Bundle. That field is incompatible with controllers in versions older than 2.401.1.3, causing the controllers to fail to start.

Environment

Resolution

The recommended solution is upgrading the controller affected to the same version that the operations center is running.

Workaround

If upgrading the controller is not an option, there are two possible workarounds:

Stop using CasC
1. Modern installations
  1. Stop the controller
  2. In operations center remove the bundle in the controller item
  3. Reprovision the controller
2. Traditional installations
  1. Stop the controller
  2. In operations center remove the bundle in the controller item
  3. Start the controller without the system property to set the link file

Upgrade the cloudbees-casc-server plugin in the operations center to a version with the fix
1. Locate the fixed version in the table above
2. Upgrade by manual installation - recommended if the operations center is not configured using a CasC bundle
  1. Download the plugin version
  2. Go to Manage > Plugin Management > Advanced > Deploy manually
3. Upgrade by Plugin Catalog - recommended if the operations center is configured using a CasC bundle
  1. Add a Plugin Catalog to the operations center bundle. It’s the same mechanism as for controllers (Example of bundle descriptor and example of plugin catalog)
    
    The plugin catalog must have a Beekeeper exception to upgrade cloudbees-casc-server to the version in the table below.
  2. Restart the operations center enabling the plugin catalog
    
    -Dcom.cloudbees.jenkins.cjp.installmanager.CJPPluginManager.enablePluginCatalogInOC=true to enable plugin catalog in OC.

The plugin version which is fixes every product version is shown below

operations center version	Affected cloudbees-casc-server version	Fixed cloudbees-casc-server version
2.401.1.3 - Released: May 31, 2023	2.3	2.3.1
2.401.2.3 - Released: June 28, 2023	2.5	2.5.1
2.401.2.5 - Released: July 3, 2023	2.5	2.5.1
2.401.2.6 - Released: July 12, 2023	2.5	2.5.1
2.401.3.3 - Released: July 26, 2023	2.13	2.13.1
2.401.3.4 - Released: August 16, 2023	2.13	2.13.1
2.414.1.4 - Released: August 28, 2023	2.16	2.16.1
2.414.2.2 - Released: September 20, 2023	2.17	2.17.1