Bundle update timing for controllers

Bundle Update Timing allows you to configure how controllers respond to new CasC bundles in your CloudBees CI instance. Key features include:

Controller configurations: Customize automatic restarts, hot reloads, and apply-on-restart for each controller.
Automatic bundle application: Alert users that bundle update requires a restart.
Manual bundle version skipping: Skip bundle versions manually to ensure controllers remain a specific version.
Default bundle skipping: Set controllers to skip new bundle versions by default to prevent automation from interfering with local controller administration.
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 for controllers

Bundle Update Timing is enabled by default when launching your instance. However, disabling Bundle Update Timing differs for traditional and modern controllers and is handled by either setting a system property via CLI or in the UI.

Disable Bundle Update Timing for traditional controllers

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 modern controllers

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 or restart are configured, then the user manually applies the new bundle version.

To configure controllers 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 controller instance can be configured to manually skip or automatically skip new bundle versions.

Skip new bundle version when the instance restarts

Users can configure their controller instance to install the latest bundle version if that version was skipped when that instance restarts.

Figure 5. Apply skipped bundle versions workflow

To configure controllers 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 controller 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 the Skip button. Select this button 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 controller 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 controllers 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 controller instance. 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.