Bundle update timing

Bundle Update Timing allows you to configure how CloudBees CI (operations center or controller) responds to new CasC bundles in your instance. Key features include:

Configurations: Customize automatic restarts, hot reloads, and apply-on-restart for your instance.
Automatic bundle application: Alert users that bundle update requires a restart.
Manual bundle version skipping: Skip bundle versions manually to ensure your instance (operations center or controller) remains a specific version.
Default bundle skipping: Set your instance to skip new bundle versions by default to prevent automation from interfering with local administration or manual changes.
Automatic bundle rejection: Set conditions to automatically reject or skip bundles.
Bundle update failure notifications: Generate notifications for bundle update failures with an explanation.

Enable and disable Bundle Update Timing

Bundle Update Timing is enabled by default at the launch of your instance. However, it can be disabled. How to disable Bundle Update Timing differs from operations centers, client controllers and managed controller.

Disable Bundle Update Timing for operations centers and client controllers (traditional)

For operations centers and client controllers, Bundle Update Timing For traditional controllers, Bundle Update Timing is disabled via command line. Set the following system property to false.

java -Dcore.casc.bundle.update.timing.enabled=false▼

Disable Bundle Update Timing for managed controllers (modern)

For modern controllers, Bundle Update Timing is disabled in the items.yaml file on the System Configuration page in the UI.

To disable Bundle Update Timing:

From the dashboard, select a controller and select Configure.
On the controller configuration page, navigate to System Properties and set core.casc.bundle.update.timing.enabled to false.

Figure 1. Disable bundle update timing system property

Configure Bundle Update Timing

If Bundle Update Timing is enabled for your instance, you can configure how and when to apply a new bundle version on the System Configuration page or in the jenkins.yaml file.

Configure Bundle Update Timing on the system configuration page

To access the System Configuration page, select Manage Jenkins System and then navigate to CasC Bundle Update Timing.

Figure 2. Bundle Update Timing configuration settings

Table 1. Bundle Update Timing configuration options

Name

Description

Notes

Automatic reload bundle

If checked, the new bundle version is automatically applied if the hot reload of the bundle can be performed. If the hot reload is not possible, reload the bundle manually by a safe restart.

This option does not apply when the instance starts. If this option and Automatic restart are both selected, Automatic reload bundle prevails.

Automatic restart

If checked, the instance performs a safe restart when the new bundle version is detected.

This option does not apply when the instance starts.

Skip new bundle versions

If checked, new bundle versions are skipped and not applied when detected.

If Automatic reload bundle and/or Automatic restart are configured, this option is ignored.

If both the Skip new bundle versions and Automatic reload bundle options are selected and the bundle cannot be hot reloaded, the bundle version is not skipped. This option is ignored when the Automatic reload bundle or the Automatic restart configuration is set.

Always reload on restart

If checked, new bundle versions reload on restart. This option only applies when the instance is starting.

If this option and the Skip new bundle versions options are selected, the new bundle version is always applied on restart and not skipped. The skip only applies when the instance is up and running.

Reject bundles with warnings

If checked, a bundle with validation warnings is rejected and not applied.

Configure Bundle Update Timing in `jenkins.yaml`

To configure Bundle Update Timing in the jenkins.yaml file:

unclassified:
  bundleUpdateTiming:
    automaticReload: false (1)
    automaticRestart: true (2)
    rejectWarnings: false (3)
    reloadAlwaysOnRestart: false (4)
    skipNewVersions: true (5)▼

1	Set the value `true` to automatically reload a new bundle version. The value is set to `false` by default.
2	Set the value to `true` automatically schedule a safe restart. The value is set to `false` by default.
3	Set the value to `true` to automatically reject bundles with validation warnings or errors. The value is set to `false` by default.
4	Set the value to `true` to automatically reload a newly detected bundle on a restart. This value is set to `false` by default.
5	Set the value to `true` to skip newly detected bundle. This value is set to `false` by default.

Automatic reload and restart

Users can configure their controllers to automatically reload or restart when a new bundle version is detected.

Figure 3. Automatic reload and restart workflow

If the automatic reload is configured and the hot reload is possible, the instance automatically reloads the new bundle.
If the automatic reload is configured and the hot reload is not possible, but the automatic restart is configured, the instance schedules a safe restart.
If the automatic reload is not configured and the automatic restart is configured, the instance schedules a safe restart.
If neither the automatic reload nor restart are configured, then the user manually applies the new bundle version.

To configure your instance to automatically reload and restart, select the following options on the System Configuration page:

Figure 4. Configure the automatic reload and restart

Skip bundles

Your CloudBees CI instance (operations center or controller) can be configured to manually skip or automatically skip new bundle versions.

Skip new bundle version when the instance restarts

Users can configure their instance (operations center or controller) to install the latest bundle version if that version was skipped when that instance restarts.

Figure 5. Apply skipped bundle versions workflow

To configure the instances to automatically skip new bundle versions, select the following options on the System Configuration page:

Figure 6. Configure skip new bundle versions

If this option and the Always reload on restart option are both selected, the new bundle version is always applied on restart and not skipped. The skip only applies when the instance is up and running.

Skip new bundle versions manually

If the CloudBees CI instance is not configured to automatically reload or skip new versions, users can manually skip the new bundle versions.

Figure 7. Manually skip new bundle versions workflow

When a new bundle version is detected, the Bundle Update tab on the CloudBees Configuration as Code export and update page displays a Skip option. Select Skip to prevent the new bundle version from being promoted.

Figure 8. Manually skip new bundle version

Automatically reject bundles with warnings

Users can configure their CloudBees CI instance to automatically reject bundles with errors. When a new bundle is detected with validation warnings or errors, the bundle is rejected and not applied.

To configure CloudBees CI (operations center or controller) to automatically reject bundles with warnings, select the Reject bundles with warnings option on the System Configuration page.

Figure 9. Configure Reject bundles with warnings

Bundle update report

The bundle update report provides a list of bundle update failures and an explanation of those failures. The report is generated when a bundle is applied to the CloudBees CI instance (operations center or controller). You can retrieve this report by downloading the Update log information.

An example of the bundle update report.

{
  "fromBundleVersion":"1",
  "toBundleVersion":"2",
  "fromBundleChecksum":"35436543e8358473543s54354354g35",
  "toBundleChecksum":"19959b86ca085cbcb412ab6c140249ed",
  "source":"AUTOMATIC", (1)
  "action":"CREATE", (2)
  "success":true,
  "skipped":false,
  "ongoingAction":false,
  "error":null
}▼

1	The source values are: MANUAL: Manual operation (reload/restart/skip) by the user in the Bundle Update tab. AUTOMATIC: Automatic reload/restart/skip. API: Manual operation (reload/restart/skip) by the user using the HTTP endpoint. CLI: Manual operation (reload/restart/skip) by the user using Jenkins CLI.
2	The action values are: RESTART: Bundle applied after a restart. RELOAD: Bundle applied after a hot reload. SKIP: Bundle skipped.