Managing Client Masters

This chapter describes how to manage your Client Masters through Operations Center.

Connecting a Client Master to Operations Center

Connecting a Client Master to Operations Center is a process that includes the following steps (Watch the ):

Prerequisites

The following instructions assume you have completed the steps for Installing the Operations Center and Installing the Client Master, and have an Operations Center and Client Master instance accessible via a web browser at the following URLs:

  • Operations Center: http://<Operations Center name>:8888

  • Client Master: http://<Client Master name>:8080

Prior to beginning the following instructions, the Operations Center and Client Master should be waiting to be unlocked with an initial admin password.

Setting up your new Operations Center

To set up your new Operations Center:

  1. Navigate to your new Operations Center.

    For example, http://<Operations Center name>:8888

  2. Copy the file location of the initial admin password on the Getting Started window.

  3. Enter the following command in your terminal:

    sudo cat + the file location you copied from step 2

  4. Copy the password value outputted from your terminal command.

  5. Paste the password value into the Administrator password box in the Getting Started window.

  6. Select Continue.

  7. Select Use a license key.

    If you have not yet purchased a CloudBees license, copy the Jenkins Instance ID and send it in an email to csm-help@cloudbees.com requesting a trial. Afterwards, a CloudBees Customer Success Manager (CSM) will create a license key and certificate for you to apply. The expected return is within 24 hours.
  8. Copy and paste the Operations Center License Key and Certificate into the respective boxes in the Enter your license key window.

    You must include the -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY----- sections.
    You must include the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- sections.
  9. Check the box next to I accept the evaluation or standard license.

  10. Select Submit.

  11. Select Install suggested plugins.

    You must install the suggested plugins. Do NOT choose Select plugins to install.
  12. Enter details for Create First Admin User.

  13. Select Save and Continue.

  14. Examine the Instance Configuration and if it looks right, select Save and Finish.

  15. Select Start using CloudBees CI Operations Center.

  16. Restart the CloudBees CI Client Master. Example URL: http://<Operations Center name>:8888/restart

  17. Select Yes.

  18. Sign in using the Admin Credentials you entered.

Creating a Folder item to organize your Client Masters

It is considered a best practice to organize your Client Masters in a Folder item because it helps align your Masters with teams or organizations and it can keep the Operations Center screen from becoming too crowded, requiring a lot of unnecessary scrolling.

To create a Folder item to hold your Client Master objects:
  1. Select New Item.

  2. Select Folder and name the folder.

    This folder will be used to organize all of the Client Master objects connected to your Operations Center.
  3. Select OK.

  4. Select the Restrict the kind of children in this folder checkbox under Properties.

  5. Select the Client Master checkbox.

  6. Select Save.

Creating a Folder to hold your Client Master objects is not a requirement, but CloudBees highly recommends it as a best practice.

Creating a new Client Master object

To create a Client Master:
  1. From the Folder you created to hold your Client Master objects, select New Client Master.

  2. Enter a name for your Client Master.

  3. Select Client Master.

  4. Select OK.

  5. Select Save.

Setting up your new Client Master

To set up your new Client Master:
  1. Navigate to your new Client Master in a new tab or window. For example, http://<Client Master name>.local:8080/

  2. Copy the file location of the initial admin password on the Getting Started window.

  3. Open a terminal and enter the following command:

    sudo cat + the file location you copied from step 2.

  4. Copy the password value outputted from your terminal command.

  5. Paste the password value into the Administrator password box in the Getting Started window.

  6. Select Continue.

  7. Select Join a CloudBees Jenkins Operations Center master.

  8. Navigate to your CloudBees CI Operations Center dashboard and select the Client Master you recently created and want to connect.

  9. Copy the Connection Details.

    You must include the ----- BEGIN CONNECTION DETAILS ----- and ----- END CONNECTION DETAILS ----- sections.
  10. Paste the Connection Details into the Connection details box in the Joining a CloudBees Jenkins Operations Center is easy window.

  11. Select Submit.

  12. Select Install suggested plugins.

    You must install the suggested plugins. Do NOT choose Select plugins to install.
  13. Enter details for Create First Admin User.

  14. Select Save and Continue.

  15. Select Start using CloudBees CI Client Master.

  16. Restart the CloudBees CI Client Master. Example URL: http://<Client Master name>.local:8080/restart

  17. Select Yes.

  18. Sign in using the Admin credentials you entered.

To verify, return to the browser tab or window of your Operations Center. You should see your new master under the folder name that was previously created. If you select the name of the Client Master, you should be redirected to the console of that Client Master. From one console you can now navigate between your Operations Center and Client Master.

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 Master. In case the Client Master 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.keyStore=$TOMCAT_LOCATION/cacert
-Djavax.net.ssl.keyStorePassword=password

Ensure that the certificates are correctly imported in both Operations Center and Client Master.

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 Master

This section describes how to configure a Client Master that has already been connected to your Operations Center instance.

To access a Client Master’s configuration:

  1. Ensure you are logged in to Operations Center as a user with the Client Master > Configure permission.

  2. From the Operations Center dashboard, select the arrow to the right of your configured Client Master (avoiding its name) and choose Configure from the dropdown menu.

    Client Master dropdown menu
    Figure 1. Client Master dropdown menu
  3. On the resulting Client Master configuration page, you can configure the following properties:

    • Description - Enter an optional description for the Client Master.

    • Health Reporting - When this checkbox is selected, health-related metrics from this Client Master 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 Master for CloudBees Jenkins Analytics are collected.

    • On-master executors - Select Enforce to specify the # of executors, which periodically ensures that the number of executors on the Client Master is the value specified in this # of executors field. Allowing items (i.e. projects or jobs) to execute directly on the Client Master 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 Master.

    • Master Owner - Specify the email address/es (one per line) of the "Owner/s" to be notified whenever this Client Master 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 master to choose a plugin catalog to apply to this Client Master. 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 Masters, as well as your build environment and infrastructure, it is usually a good idea to restrict your Client Masters' access to the Internet as part of a process known as air gapping. [airgap]

However, Pipelines and other types of build projects configured on your Client Masters and other CloudBees CI Masters 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 Masters.

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 Masters 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:

  1. Ensure you have installed an artifact repository system within your organization’s infrastructure, and ensure the artifact repository has access to the Internet.

  2. 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 Proxy  Remote storage 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 Repository Management 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 Master plugins

Like how Operations Center makes it easy to install and update plugins, a Client Master also makes it easy to install and update plugins that extend its functionality. Refer to the Plugin management guide for details.

Configuring Client Masters through CLI

Jenkins allows some operations to be invoked through CLI, some of them being useful to configure Client Masters. Refer to Managing plugins from the Client Masters 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 Master

When using CloudBees CI on modern cloud platforms, if a Client Master 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 Masters or if you decide you do not want to use the Operations Center, you can release your Client Masters.

Releasing a Client Master will permanently remove it from the Operations Center cluster.

The connection details that the Client Master has will be invalidated and new connection details will need to be pushed to rejoin the Client Master 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 Master in two ways:

  1. Using the UI

  2. Using the CLI

To release a Client Master from the Operations Center using the UI:

  1. Navigate to the dashboard of your Operations Center.

  2. Select the gear icon for managing the Client Master you want to release.

  3. Select Disconnect under Manage in the left navigation pane.

    You must disconnect the Client Master before you can release it.
  4. Select Release under Manage in the left navigation pane.

To release a Client Master from Operations Center using the CLI:

  1. Get the Jenkins CLI tool

  2. Use the Jenkins CLI tool

  3. Enter the following command:

    java -jar jenkins-cli.jar -s https://<operations-center-url>/cjoc/ -webSocket client-master-release NAME

    Replace <operations-center-url> and NAME with your values.