This chapter describes how to manage your client controllers through operations center.
Running on a TLS end-point
If the operations center instance is deployed on a TLS end-point, you must import the SSL certificate in the Java Keystore of the client controller. In case the client controller is deployed on a Tomcat web container, you might need to tell what keystore Jenkins is using. This should verify that Tomcat is using the correct keystore.
If it is not in the standard location ($JAVA_HOME/jre/lib/security/cacerts), add it as part of the Java arguments:
-Djavax.net.ssl.trustStore=$TOMCAT_LOCATION/cacert -Djavax.net.ssl.trustStorePassword=password
Ensure that the certificates are correctly imported in both operations center and client controller.
keytool -keystore /$JRE_HOME/lib/security/cacerts -v -list
The cacert file should have file system read permission granted to the operating system user running the Jenkins JVM.
Configuring a client controller
This section describes how to configure a client controller that has already been connected to your operations center instance.
To access a client controller’s configuration:
-
Ensure you are logged in to operations center as a user with the Client controller > Configure permission.
-
From the operations center dashboard, select the arrow to the right of your configured client controller (avoiding its name) and choose Configure from the dropdown menu.
Figure 1. Client controller dropdown menu -
On the resulting client controller configuration page, you can configure the following properties:
-
Description - Enter an optional description for the client controller.
-
Configuration as Code (CasC) - Select the configuration bundle to assign to the controller. The list of available bundles is filtered using the Availability pattern from the Configuration as Code bundles screen. By default, no bundles are included in the list. For more information, see Assigning a bundle to a controller.
-
Health Reporting - When this checkbox is selected, health-related metrics from this client controller are collected periodically. The default data collection period is once per minute, when data consumers are present (e.g. Weather columns or CloudBees Jenkins Analytics).
-
Analytics Reporting - When this checkbox is selected, report events and other metrics from this client controller for CloudBees Jenkins Analytics are collected.
-
On-controller executors - Select Enforce to specify the # of executors, which periodically ensures that the number of executors on the client controller is the value specified in this # of executors field. Allowing items (i.e. projects or jobs) to execute directly on the client controller is a security risk since such projects/jobs could potentially access the file system and the build records of all previously run projects/jobs (which may contain sensitive information). Therefore, set this value to 0 to prevent any items from being executing directly on the client controller.
-
Controller Owner - Specify the email address/es (one per line) of the "Owner/s" to be notified whenever this client controller goes offline or changes state.
Selecting the Advanced button opens the Delay before notification field, which allows you to specify the number of minutes (a value between 1 and 60) between notifications. -
Plugin Catalog - Select Specify a plugin catalog for this controller to choose a plugin catalog to apply to this client controller. You can also allow Beekeeper plugin exceptions with a plugin catalog. See Beekeeper plugin exceptions - Setting up Beekeeper plugin exceptions for more information.
-
Setting up a proxy artifact repository
To maintain the security of client controllers, as well as your build environment and infrastructure, it is usually a good idea to restrict your client controllers' access to the Internet as part of a process known as air gapping.
However, Pipelines and other types of build projects configured on your client controllers and other CloudBees CI Controller are likely to require access to artifact repositories on the Internet, since artifacts from such external and/or trusted repositories may need to be integrated into these build projects' builds. Additionally, these external artifact repositories may also house custom plugins, which you can define and configure in a plugin catalog, to install these plugins on your client controllers.
For instance, the publicly accessible repository https://repo.jenkins-ci.org/releases/ is one such artifact repository to which the Jenkins Community publishes Maven artifacts, as well as hpi/plugin files.
Therefore, to provide your client controllers with access to content housed by these external artifact repositories, set up a proxy artifact repository (with access to the Internet) internally within your organization’s infrastructure.
To set up a proxy artifact repository to an external artifact repository:
-
Ensure you have installed an artifact repository system within your organization’s infrastructure, and ensure the artifact repository has access to the Internet.
-
Some popular artifact repository systems include:
-
Sonatype’s Nexus Repository, available in free Jenkins LTS and Pro editions.
-
JFrog’s Artifactory.
-
-
To install either Sonatype Nexus Repository edition, refer to their installation instructions.
-
To install JFrog Artifactory, refer to their installation instructions.
-
-
In your artifact repository system, configure your proxy artifact repository to your external or publicly accessible artifact repository.
-
For Sonatype’s Nexus Repository, configure the option in your new proxy artifact repository’s settings. Read more about configuring a proxy artifact repository in Nexus Repository using their Repository Management documentation, as well as the Proxy > Remote Storage sub-section of the Managing Repositories and Repository Groups section of this documentation.
-
For JFrog’s Artifactory, read more about configuring a proxy artifact repository in JFrog Artifactory using their Managing Proxies documentation.
-
Installing and updating client controller plugins
Like how operations center makes it easy to install and update plugins, a client controller also makes it easy to install and update plugins that extend its functionality. Refer to the Plugin management guide for details.
Configuring client controllers through CLI
Jenkins allows some operations to be invoked through CLI, some of them being useful to configure client controllers. Refer to Managing plugins from the client controllers command line for details.
Configuring Plugin Catalogs
The Beekeeper Upgrade Assistant feature of the Manage Jenkins area of operations center is the main interface and entry point to the CloudBees Assurance Program.
Beekeeper Upgrade Assistant manages appropriate upgrades (and downgrades) of plugins on your operations center instance, in accordance with the CloudBees Assurance Program.
Refer to Configuring plugin catalogs for details.
Releasing a client controller
When using CloudBees CI on modern cloud platforms, if a client controller is no longer necessary or if it is no longer required for it to be connected to the operations center, it should be released.
When using CloudBees CI on traditional platforms, if you want to stop managing some of your client controllers or if you decide you do not want to use the operations center, you can release your client controllers.
Releasing a client controller will permanently remove it from the operations center cluster.
The connection details that the client controller has will be invalidated and new connection details will need to be pushed to rejoin the client controller with an operations center cluster.
Access to any licenses or other resources that have been provided by the operations center cluster will be removed.
You can release a client controller in two ways:
-
Using the UI
-
Using the CLI
To release a client controller from the operations center using the UI:
-
Navigate to the dashboard of your operations center.
-
Select the gear icon for managing the client controller you want to release.
-
Select Disconnect under Manage in the left navigation pane.
You must disconnect the client controller before you can release it. -
Select Release under Manage in the left navigation pane.
To release a client controller from operations center using the CLI:
-
Enter the following command:
java -jar jenkins-cli.jar -s https://<operations-center-url>/cjoc/ -webSocket client-master-release NAMEReplace <operations-center-url>andNAMEwith your values.