Updating a CasC bundle

4 minute readScalabilityAutomation

When a bundle update is available, an alert is displayed in the Manage Jenkins screen.

Figure 1. Bundle update alert

You can also check for updates on the CloudBees Configuration as Code export and update screen on the Bundle update tab.

To check for bundle updates:

  1. Ensure you are signed in as a user with the Overall/Manage permission.

    This option is available to users with the Overall/Manage permission, allowing users with the Administrator role to delegate this task. For more information, refer to Delegating Administration.
  2. Navigate to the controller.

  3. Select Manage Jenkins in the left pane.

  4. Select CloudBees Configuration as Code export and update.

  5. Select the Bundle update tab. A blue bell appears next to the tab if an update is detected.

  6. Select Check for Updates.

    If a controller is configured with a bundle using the -Dcore.casc.config.bundle=/path/to/casc-bundle Java system property, a bundle update is detected only when the version attribute in the bundle.yaml file has been incremented. If the version attribute is not incremented, the bundle update is not detected and cannot be applied.
    Figure 2. Check for updates
  7. If bundle updates are available, select one of the following options:

    • Safe Restart: Performs a restart and applies the new bundle. CloudBees recommends this option because you can determine an appropriate time to restart and apply the updated bundle.

    • Reload Configuration: Applies the new configuration without a restart. This is called a "hot reload". For more information on when hot reload is appropriate, refer to Using hot reload on a configuration bundle.

      Figure 3. New bundle version

Configuring the bundle update recurrence period

After the initial configuration on startup, a background process automatically checks for bundle updates every twenty minutes.

Optionally, you can customize this by setting the Java system property com.cloudbees.opscenter.client.casc.ConfigurationUpdaterTask.recurrencePeriod to the desired interval, in minutes.

For example, to check for updates every five minutes, use the following startup command:

java -Dcore.casc.config.bundle=$JENKINS_HOME/casc-bundle-link.yaml \
 -Dcom.cloudbees.opscenter.client.casc.ConfigurationUpdaterTask.recurrencePeriod=5 \
 -jar jenkins.war
Figure 4. Bundle update

Using CasC gives you great power and flexibility, which introduces the possibility for errors that could impact your installation. Please review the information below to help guide you as you evolve your CasC bundle.

Risks when updating the bundle.yaml file

If a controller is configured with a bundle using the -Dcore.casc.config.bundle=/path/to/casc-bundle Java system property, a bundle update is detected only when the version attribute in the bundle.yaml file has been incremented. If the version attribute is not incremented, the bundle update is not detected, and cannot be applied.

Risks when updating the plugins.yaml file

You can install CloudBees Assurance Program (CAP) Tier 1 and Tier 2 plugins by adding the plugins to the plugins.yaml file.

You can also install non-CAP or Tier 3 plugins to the controller by adding the plugins to the plugins.yaml file and to the plugin-catalog.yaml file. For more information, refer to Risks when updating the plugin-catalog.yaml file.

CAP Tier 1 and Tier 2 plugins

To get the list of CloudBees Tier 1 and Tier 2 plugins:

  1. Navigate to CloudBees CI Plugins.

  2. To verify that your plugin is a CAP Tier 1 or Tier 2 plugin, you can either:

    • Search for a specific plugin and filter based on Verified or Proprietary (Tier 1) or Compatible (Tier 2).

    • Scroll to the bottom of the page and select All Tier 1 plugins to browse all Tier 1 plugins and then filter by Tier.

For more information on the CAP and how CloudBees classifies plugins, refer to CloudBees plugin support policies.

Uninstalling a plugin

There are no "delete/uninstall” operations when using CasC, and you cannot uninstall plugins by removing the plugins from the plugins.yaml file.

To uninstall a plugin:

  1. Uninstall the plugin in the UI.

  2. Before restarting, remove the plugin IDs from the plugins.yaml file. Otherwise, the plugins will be reinstalled.

Risks when updating the plugin-catalog.yaml file

You can install non-CAP or Tier 3 plugins to the controller by adding the plugin to the plugins.yaml file and to the plugin-catalog.yaml file.

The plugins in this file must be compatible with the set of CAP Tier 1 or Tier 2 plugins in the plugins.yaml file. A validation of the plugin-catalog.yaml file runs at startup. If this validation fails, the plugin in the plugin-catalog.yaml file is not installed and the controller continues with its normal startup, which may lead to other problems. For example, specific configurations in the jenkins.yaml cannot be applied.

For more information on plugin catalogs, refer to Installing non-CAP plugins with plugin catalogs.

Risks when updating the jenkins.yaml file

This file can be edited to change or add Jenkins configurations. There are a wide variety of possible combinations, depending on the plugins that are configured as code. This file is managed by the Jenkins LTS - Configuration as Code (JCasC) plugin. Therefore, all Jenkins LTS documentation, reported bugs, community blogs, Gitter chats, etc., apply to this file.

The bulk of the content in this file is defined by the various plugins you have installed with only a small portion of it defined by the Jenkins core itself. However, there are a few general items to consider when editing the file:

  • Removing a configuration from this file does not remove the configuration from an existing controller or operations center instance.

  • Adding configurations requires the underlying plugin that the configuration references to be installed. Jenkins startup will fail otherwise.

  • Backward compatibility depends on the specific plugins that are being configured. If a plugin changes its configuration in an incompatible way, then the controller or the operations center will fail to start until the jenkins.yaml file is adapted, or the section in the file that is related to the plugin is removed.

  • This file may contain data which is tied to a specific CloudBees instance, such as encoded secrets, the operations center connection details, and others, so a jenkins.yaml is, in general, suitable for a single CloudBees controller instance. This might lead to indecipherable secrets, controller to operations center connection failing, and many more things depending on the specific configuration.

Using hot reload on a configuration bundle

CasC allows you to reload a configuration file without restarting the instance. Since the CasC API plugin manages plugin updates and the plugin catalog, validating a hot reload is a more complex process. A bundle reload is not always possible.

If plugin upgrades are in the updated bundle, Jenkins must be restarted.

If a hot reload is possible, the following operations are automatically performed:

  • Update the plugin catalog.

  • Install any new plugins.

  • Call the API on configuration as code to reload the Jenkins configuration.

Configuration bundles that do not include plugin updates can be reloaded without an instance restart. This feature allows you to update Jenkins configurations, install new plugin catalogs, or install new plugins dynamically.