Integrate multiple controllers with the CloudBees CI operations center

CloudBees limited preview

This documentation describes features and functionality available only to customers in the CloudBees Limited Preview Program for early access and feedback. It is provided for informational purposes only and is subject to change without notice. While this feature is in limited preview, your experience may vary. CloudBees recommends stringent testing in a development environment and a complete review of the documentation and architecture before using it in production.

Integrate your CloudBees CI operations center with CloudBees Unify to automatically discover and connect all controllers managed by the operations center. This method connects multiple controllers at once, rather than integrating them individually.

To integrate single CloudBees CI or Jenkins controllers, refer to Integrate a single controller with CloudBees Unify.

Set up the integration

Follow these steps to integrate your operations center and controllers with CloudBees Unify.

Table 1. Integration steps
Step	Where	Action
1	Your controllers	Set up a CloudBees CI Multibranch Pipeline or an Organization Folder with a GitHub, Bitbucket, or GitLab branch source.
2	Your operations center and controllers	Install the required plugin to the operations center and controllers.
3	Your controllers	(Optional) Opt out specific controllers
4	CloudBees Unify	Create the CloudBees CI Operations Center integration.
5	CloudBees Unify	View and monitor controller status.
6	CloudBees Unify	Create an SCM integration for the Multibranch or Organization Folder code source.
7	CloudBees Unify	Create a component with the integrated source code.

System specifications

This CloudBees Unify feature has the following technical requirements and limitations. These factors may evolve.

Use a CloudBees CI or Jenkins Multibranch Pipeline or Organization Folder, as other project types are not supported.
Use a GitHub, Bitbucket, or GitLab branch source for the Multibranch Pipeline or Organization Folder. Other SCM providers are not supported at this time.
Create an SCM integration between the SCM repository associated with your Multibranch Pipeline or Organization Folder and CloudBees Unify.
If your Multibranch or Organization Folder contains more than one repository, only the first detected SCM repository is considered by CloudBees Unify.
Only CI jobs and builds executed from your controller after integrating with CloudBees Unify are displayed.

Set up a CloudBees CI Multibranch Pipeline or an Organization Folder

Set up a CloudBees CI Multibranch Pipeline or an Organization Folder on your controllers with a GitHub, Bitbucket, or GitLab branch source. Refer to Create Multibranch Projects and Organization Folders with large repositories for details.

GitLab Cloud and Bitbucket Data Center are supported.

Install the required plugin to the operations center and controllers

This integration requires the following plugins:

CloudBees Platform Integration Plugin::OC (cloudbees-cbp-unify-integration-oc): Installed on the operations center.
CloudBees Platform Integration Plugin::Controllers (cloudbees-cbp-unify-integration): Installed on each controller.

Choose one of the following installation methods:

Install the plugin from the CloudBees CI UI
Install the plugin using CasC

Install the plugin from the CloudBees CI UI

Install the plugin using the CloudBees CI plugin manager.

To install plugin to the operations center:

From the operations center dashboard, select in the upper-right corner to navigate to the Manage Jenkins page.
Select Plugins Available plugins.
In the Search available plugins field, enter CloudBees Platform Integration Plugin::OC.
Select the checkbox next to the plugin.
Select Install in the upper-right corner.

To install plugin to the controllers:

From the controller dashboard, select in the upper-right corner to navigate to the Manage Jenkins page.
Select Plugins Available plugins.
In the Search available plugins field, enter CloudBees Platform Integration Plugin::Controllers.
Select the checkbox next to the plugin.
Select Install in the upper-right corner.

Install the plugin using CasC

CloudBees CI Configuration as Code (CasC) is the recommended approach for large-scale deployments with many controllers, as it allows you to configure plugins and settings across your entire CloudBees CI environment efficiently.

To install the plugins using CasC:

Create the operations center bundle.
Create controller bundles.
Apply the CasC bundles.

These plugins are not yet in the CloudBees Assurance Program (CAP). Use CasC Plugin Management 2.0 to automatically manage plugin dependencies. CasC Plugin Management 2.0 requires apiVersion:2 in the bundle.yaml file.

Create the operations center bundle

Create a CasC bundle for your operations center that includes the following files. For more information, refer to Create CasC bundles.

bundle.yaml: Index file that describes the bundle and references the other files. This file must specify apiVersion:2 for CasC 2.0.
plugins.yaml: Specifies the plugins to install on the operations center.
jenkins.yaml: Contains the Jenkins configuration for the operations center.
items.yaml: Defines the controllers and their configurations, including opt-in/opt-out settings.

Example operations center plugins.yaml file

plugins:
  - id: "cloudbees-cbp-unify-integration-oc"▼

Create controller bundles

Create CasC bundles for your controllers that include the following files:

bundle.yaml: Index file that describes the bundle and references the other files. This file must specify apiVersion:2 for CasC 2.0.
plugins.yaml: Specifies the plugins to install on each controller.

Example controller plugins.yaml file

plugins:
  - id: "cloudbees-cbp-unify-integration"▼

Apply the CasC bundles

Apply the operations center bundle to your operations center and the controller bundles to your controllers. The plugins are installed and the configuration is applied automatically.

Refer to the following for details on creating and applying CasC bundles:

(Optional) Opt out specific controllers

To exclude specific controllers from automatic integration, configure them to opt out using one of the following methods:

Opt out from the operations center UI
Opt out using CasC

Opt out from the operations center UI

To opt out a controller from the operations center UI:

From the operations center dashboard, select next to the controller.
Select Configure in the left pane.
Scroll down to CloudBees platform configuration.
Select Opt out of auto configuration.
Select Save.

If you opt out a controller after the operations center integration is already established, manually sync the changes to CloudBees Unify from your operations center by selecting , and then selecting Send all Controller connection data to CloudBees Platform.

Opt out using CasC

To opt out a controller using CasC, configure the opt-out setting in the operations center bundle’s items.yaml file. For example:

items:
- kind: managedController
  name: my-controller
  description: my-controller
  displayName: my-controller
  properties:
  - cbpOptOut:
      optOut: true(1)▼

1	Set to `true` to opt out the controller from automatic integration, or `false` to opt in.

If you opt out controllers after the operations center integration is already established, manually sync the changes to CloudBees Unify from your operations center by selecting , and then selecting Send all Controller connection data to CloudBees Platform.

Create the CloudBees CI Operations Center integration

After installing the required plugins to your operations center and controllers, create an operations center integration in CloudBees Unify.

View and monitor controller status

After creating the operations center integration, monitor the connection status of individual controllers.

To view the controller status:

In the CloudBees Unify, navigate to Configurations Integrations.
Find the operations center integration record.
Select for the new operations center record, and then select View controllers.

The View controllers screen displays the status of each controller:
- Waiting for connection: The controller is pre-registered via the operations center integration and is in the process of connecting to CloudBees Unify.
- Connected: The controller is successfully connected with CloudBees Unify and can start sending data.

The Last data received column displays the timestamp of when CloudBees Unify last received job data from each controller. This timestamp updates when job data is received from Multibranch Pipeline jobs.

Troubleshoot the controller connection status

The following table lists common issues and resolutions when monitoring controller connection status.

Table 2. Troubleshoot controller connection status
Issue	Resolution
A controller remains in Waiting for connection status for an extended period.	The controller may be hibernating, offline, or missing the required plugin. Verify the following: The controller is up and running (not hibernated). The CloudBees Platform Integration Plugin::Controllers is installed on the controller. If the plugin is not installed, install it and allow up to one hour for connection, or restart the controller to speed up detection.
Last data received shows `No data sent` even though the controller status is Connected.	The Last data received field displays the latest timestamp of when CloudBees Unify received job data from the controller. If the controller has no Multibranch Pipeline jobs configured, this field shows `No data sent` even when connected.
Opted out controllers still appear in the View controllers table, or their status has not updated.	If you opted out controllers after the operations center integration was already established, manually sync the changes to CloudBees Unify from your operations center: Select in the upper-left corner. Select Send all Controller connection data to CloudBees Platform.
A controller went offline, was shut down, or was hibernated after the operations center integration was established, but the status still shows Connected.	Manually sync the changes to CloudBees Unify from your operations center: Select in the upper-left corner. Select Send all Controller connection data to CloudBees Platform.

Create an SCM integration

After your controllers are integrated with CloudBees Unify, create an SCM integration for the Multibranch Pipeline or Organization Folder code source.

Create an integrated component

To fully integrate a CI pipeline with CloudBees Unify, create a component to link the source code in your controllers with CloudBees Unify. Each component connects to a single source code repository via an SCM integration. By creating a component for your pipeline source code, you can facilitate the management of complex CI pipelines and ensure traceability and insight into your SDLC. Components ensure that all code updates are systematically processed, logged, and integrated, enhancing the scalability and reliability of software delivery.

Create an SCM integration with CloudBees Unify for the Multibranch or Organization Folder project code source on your controllers.
Create a CloudBees Unify component with the integrated source code to enable metrics for your project.
- indicates a repository integrated with a Multibranch Pipeline that you can select to create a component.
- If you do not find your repository listed with , select Set up your controller to confirm that it is connected to the CI controller.
  
  Figure 1. An integrated repository is highlighted
  
  The component for your integrated CI pipeline is created accordingly.

Next steps

After you integrate your CI with CloudBees Unify, you can:

Visualize details of your CI jobs and builds, including test results and build artifacts.
Set up automatically triggered implicit security analysis.
Create an application, which enables you to orchestrate complex software releases.
Monitor your integrated CI data in CloudBees Unify value stream management (VSM) dashboards.