Create an alternate plugin download site

When installing plugins in Configuration as Code (CASC), CloudBees CI defaults to using CloudBees Update Centers (UC). However, there are specific scenarios where users may want to set their own infrastructure as the default location to manage plugins instead of directly accessing the UC:

Air-gapped Environments: Systems isolated from unsecured networks like the internet.
High-Security Restrictions: Access to the UC is unreliable or restricted.

Creating a mirror server of the UC allows users in one of the scenarios described above to manage and download their plugins.

Set up CloudBees CI to use a mirror of the update center

Create a mirror of the UC and then configure your CloudBees CI environment to use it. Configuration is only applicable when you manage plugins using CasC.

This setup does not change plugin management in CloudBees CI; it only allows for the configuration of a UC mirror if CloudBees CI is configured using CasC.
This setup works for CasC plugin management with:
- apiVersion: 1: Only supports Plugin Catalog
- apiVersion: 2: Supports Plugin Catalog and non-CAP plugins downloaded from the UC.

To set up CloudBees CI to use and configure a UC mirror:

There are several methods available for setting up a UC mirror server. Therefore, creation and maintenance of the UC mirror fall under the user’s infrastructure and responsibility and is not managed within CloudBees CI. This allows users to choose the approach that best suits their requirements.

Mirror one of the following UC content:
1. JSON file only. Contains all data offered by the Update Center in JSON format (core version, download URLs, plugins, and dependencies of plugins).
2. Plugins only.
3. Plugins and the JSON data. CloudBees recommends mirroring this content.

Add system properties to configure your CloudBees CI environment to use the UC mirror server via your CLI:

If mirroring the JSON file only, add com.cloudbees.jenkins.cjp.installmanager.casc.plugin.management.CloudBeesUCUrlConfiguration.json.
If mirroring the plugins only, add com.cloudbees.jenkins.cjp.installmanager.casc.plugin.management.CloudBeesUCUrlConfiguration.plugins.

If mirroring both the plugins and JSON data, add com.cloudbees.jenkins.cjp.installmanager.casc.plugin.management.CloudBeesUCUrlConfiguration.root.

CloudBees recommends using com.cloudbees.jenkins.cjp.installmanager.casc.plugin.management.CloudBeesUCUrlConfiguration.root system parameter. If necessary, you can configure com.cloudbees.jenkins.cjp.installmanager.casc.plugin.management.CloudBeesUCUrlConfiguration.json to set the path to a local file. However, CloudBees only recommends this configuration if the size of the JSON file causes some network issues when downloading using http(s). All checks still applies regardless the source of the JSON file.

If the json or plugins system properties are set, their values prevail over the root system property.

The UC mirror server must expose the JSON files and plugins using the same structure as the original CloudBees UC.

JSON file: http://MIRROR_SERVER_URL/envelope-{productId}/update-center.json?id={productId}&version={productVersion}
Plugins: http://MIRROR_SERVER_URL/download/plugins/{pluginId}/{pluginVersion}/{pluginId}.hpi

Example of UC mirror configurations and the resulting URL

The following examples show UC mirror configurations and the resulting URLs for sample plugins.

Example of download URLs for Beer 1.0 plugin

# If no system property is set, then the CloudBees UC is used
-Dcom.cloudbees.jenkins.cjp.installmanager.casc.plugin.management.CloudBeesUCUrlConfiguration.plugins=http://my-server → http://my-server/beer/1.0/beer.hpi

-Dcom.cloudbees.jenkins.cjp.installmanager.casc.plugin.management.CloudBeesUCUrlConfiguration.plugins=http://my-server:8080/my-context → http://my-server:8080/my-context/beer/1.0/beer.hpi

-Dcom.cloudbees.jenkins.cjp.installmanager.casc.plugin.management.CloudBeesUCUrlConfiguration.root=http://my-server → https://my-server/download/plugins/beer/1.0/beer.hpi

-Dcom.cloudbees.jenkins.cjp.installmanager.casc.plugin.management.CloudBeesUCUrlConfiguration.root=http://my-server:8080/my-context → https://my-server:8080/my-context/download/plugins/beer/1.0/beer.hpi▼

Examples of download URLs for UC data core-cm:2.452.2.4

# If no system property is set, then the CloudBees UC is used
-Dcom.cloudbees.jenkins.cjp.installmanager.casc.plugin.management.CloudBeesUCUrlConfiguration.json=http://my-server → http://my-server/envelope-core-cm/update-center.json?id=core-cm&version=2.452.2.4

-Dcom.cloudbees.jenkins.cjp.installmanager.casc.plugin.management.CloudBeesUCUrlConfiguration.json=http://my-server:8080/my-context → http://my-server:8080/my-context/envelope-core-cm/update-center.json?id=core-cm&version=2.452.2.4

-Dcom.cloudbees.jenkins.cjp.installmanager.casc.plugin.management.CloudBeesUCUrlConfiguration.root=http://my-server → https://my-server/update-center/envelope-core-cm/update-center.json?id=core-cm&version=2.452.2.4

-Dcom.cloudbees.jenkins.cjp.installmanager.casc.plugin.management.CloudBeesUCUrlConfiguration.root=http://my-server:8080/my-context → https://my-server:8080/my-context/update-center/envelope-core-cm/update-center.json?id=core-cm&version=2.452.2.4▼

The JSON data file must match the CloudBees CI version, otherwise it will fail. CloudBees CI will not fallback on the original UCs if the data downloaded using the system property is not valid. It is the user’s responsibility to properly configure the system properties and the mirror server.

Additionally, if the JSON data or the hpi downloaded from the mirror server is not correct because of a misconfiguration on the server side, CloudBees is not responsible for this behaviour.

Manipulating the UC data is not supported. This setup only works with the real mirrored UC data.

Deploy the UC mirror configuration on CloudBees CI on modern cloud platforms

Use Helm Chart to deploy the mirror configuration.

This adds the system properties to the operations center. For the controllers, add the system property in the Java Options section of the controller configuration page. Refer to Adding system properties when initializing a managed controller for more information.

In the values.yaml:

Set OperationsCenter.CasC.Enabled=true to enable CasC.
Enable the following system properties:
1. Set the OperationsCenter.CasC.UCurl.root value for com.cloudbees.jenkins.cjp.installmanager.casc.plugin.management.CloudBeesUCUrlConfiguration.root system property.
2. Set the OperationsCenter.CasC.UCurl.json value for the com.cloudbees.jenkins.cjp.installmanager.casc.plugin.management.CloudBeesUCUrlConfiguration.json system property.
3. Set the OperationsCenter.CasC.UCurl.plugins value for the com.cloudbees.jenkins.cjp.installmanager.casc.plugin.management.CloudBeesUCUrlConfiguration.plugins.