Advanced topics

5 minute readScalabilityAutomation

Enabling HTTPS

The security token and Configuration as Code (CasC) for Controllers bundle both contain sensitive information, so it is recommended that they are protected by using HTTPS when sent between the operations center and controller. HTTPS must be enabled on the operations center side. Typically enabling HTTPS is done by terminating the secure connection externally in a reverse proxy, but it can also be terminated in the Jenkins server. To enable HTTPS, add startup parameters to specify the HTTPS port, server certificate, and key.

Example startup parameters

java -jar jenkins.war --httpsPort=8443 \
--httpsCertificate=/etc/certs/jenkins-cert.cert \
--httpsPrivateKey=/etc/certs/jenkins-cert.key

Using a self-signed certificate

This configuration is not recommended and should not be used in production.

If you are using this method in a limited scope for test deployments, refer to Set-up SSL on a CJP environment with a self-sign SSL certificate on each Jenkins box, a CloudBees Knowledge Base article, for guidance on setting up CloudBees CI with a self-signed certificates.

Calculating plugin dependencies

The Plugin Installation Manager Tool can be used to assist with determining the full list of a plugin’s transitive dependencies. The tool takes as input a plugins.yaml that lists plugins you would like to install and outputs a list of all the plugins to be installed, along with all their transitive dependencies. This list can then be used to populate the plugin catalog so the plugins specified in plugins.yaml can be successfully installed.

The plugins.yaml file used by the tool is not the same as the one created previously when authoring the Configuration as Code (CasC) for Controllers bundle.

Prerequisites

  • The plugin.yaml file from the Configuration as Code (CasC) for Controllers bundle

  • Java Developer Kit (JDK) installed and configured

  • Apache Maven installed and configured

  • (Optionally) git installed and configured

  • Access to the jenkins.war file that will be used to create the connected controller

To create a list of plugins to be installed including all transitive dependencies:

  1. Clone (or download) the Plugin Installation Manager Tool’s repository from https://github.com/jenkinsci/plugin-installation-manager-tool.

  2. Build the tool using the following commands:

    cd plugin-installation-manager-tool
    mvn clean package
  3. Using the plugins.yaml file from the Configuration as Code (CasC) for Controllers bundle, create a plugins.yaml file for use with the tool. Rename the Configuration as Code (CasC) for Controllers bundle’s plugins.yaml file’s YAML property id to artifactId as illustrated below:

    plugins.yaml from Configuration as Code (CasC) for Controllers bundleplugins.yaml for use with tool
    plugins:
      - id: "git"
      - id: "maven-plugin"
    plugins:
      - artifactId: "git"
      - artifactId: "maven-plugin"
  4. Run the tool, using the following command, updating it with the location of your controller .war file and the location of your plugins.yaml file:

    cd plugin-installation-manager-tool
    java -jar \
    plugin-management-cli/target/jenkins-plugin-manager-*.jar \
    --no-download --plugin-download-directory plugin-download \
    --list \
    --war $JENKINS_HOME/cloudbees-core-cm.war \  // (1)
    --plugin-file plugins.yaml // (2)
    1location of controller .war file
    2location of plugins.yaml file

Sample output file with list of plugins

File containing list of plugins to be downloaded: plugins.yaml
Reading in plugins from plugins.yaml

Plugin download location: plugin-download
No CLI option or environment variable set for update center, using default of https://updates.jenkins.io
No CLI option or environment variable set for experimental update center, using default of https://updates.jenkins.io/experimental
No CLI option or environment variable set for incrementals mirror, using default of https://repo.jenkins-ci.org/incrementals
Will use war file: $JENKINS_HOME/jenkins.war

Installed plugins:

Bundled plugins:

Set of all requested plugins:
chucknorris 1.2
workflow-step-api 1.14

Set of all requested plugins that will be downloaded:
chucknorris 1.2
workflow-step-api 1.14

Set of all existing plugins and plugins that will be downloaded:
chucknorris 1.2
workflow-step-api 1.14
Done

Find the section in your output titled Set of all requested plugins that will be downloaded. This section is the list of plugins that will need to be added to plugin-catalog.yaml to successfully install the plugins.yaml.

You may get significantly more output than the example, especially in the “Bundled Plugins” and “Set of all existing plugins and plugins that will be downloaded” sections.

Configuring bundle inheritance with CasC

You can simplify bundle composition and maintenance by creating a "child" bundle that inherits common configuration elements from a "parent" bundle. This allows you to maintain common configuration elements in a single parent bundle that are automatically inherited by all bundles in the inheritance chain, eliminating the need to manually maintain and update individual bundles.

To configure bundle inheritance, add a parent property to the child bundle’s bundle.yaml file.

  • If making a change to a bundle, do not apply the change to all controllers at once. Instead, apply the change to a single controller-specific bundle, verify it works as expected, and then apply the change to all bundles.

  • Child bundles must only contain configuration elements that are unique to that bundle and should not overwrite the parent bundle’s configuration elements.

Example bundle inheritance

In this example, there are two child bundles: bundle-1 and bundle-2. There is also a parent bundle: bundle-global.

$JENKINS_HOME/jcasc-bundles-store/
├── bundle-1 (1)
│   ├── bundle.yaml
├── bundle-2 (2)
│   ├── bundle.yaml
│   └── plugins.yaml
└── bundle-global
    ├── bundle.yaml
    ├── jenkins.yaml
    └── plugins.yaml
1bundle-1 inherits from bundle-global and uses the same jenkins.yaml and plugins.yaml files as bundle-global.
2bundle-2 inherits from global and uses the same jenkins.yaml file as global, but includes a unique plugin in its plugins.yaml file.

bundle-global example

Within bundle-global, the bundle.yaml file defines:

  • The bundle’s unique id: "bundle-global".

  • The contents of the bundle: a plugins.yaml file and jenkins.yaml file.

id: "bundle-global"
version: "1"
apiVersion: "1"
description: "Global bundle with common configuration elements"
plugins:
  - "plugins.yaml"
jcasc:
  - "jenkins.yaml"

bundle-global includes a plugins.yaml file that contains a list of all plugins to install on the controller:

plugins:
  # In CAP
  - { id: "cloudbees-casc-api" }
  - { id: "configuration-as-code" }
  - { id: "git" }
  - { id: "maven-plugin" }
  - { id: "nectar-rbac" }

bundle-global includes a jenkins.yaml file that describes the controller:

jenkins:
  systemMessage: "Jenkins configured using CasC."
  numExecutors: 0
  mode: NORMAL
  securityRealm:
    local:
      allowsSignup: false
      users:
       - id: admin
         password: admin
       - id: developer
         password: developer
       - id: read
         password: read

bundle-1 example

Within bundle-1, the bundle.yaml file defines:

  • The bundle’s unique id: "bundle-1".

  • The parent bundle to inherit from: "bundle-global".

  • The contents of the bundle that are unique to the child bundle. Since bundle-1 inherits the plugins.yaml and jenkins.yaml files from bundle-global, no additional bundle information is required.

id: "bundle-1"
version: "1"
apiVersion: "1"
description: "My CloudBees Configuration as Code (CasC) bundle"
parent: "bundle-global"

bundle-2 example

Within bundle-2, the bundle.yaml file defines:

  • The bundle’s unique id: "bundle-2".

  • The parent bundle to inherit from: "bundle-global".

  • The contents of the bundle that are unique to the child bundle. bundle-2 inherits the plugins.yaml and jenkins.yaml files from bundle-global. However, bundle-2 also requires an additional plugin that is not included in the bundle-global.

id: "bundle-2"
version: "1"
apiVersion: "1"
description: "My CloudBees Configuration as Code (CasC) bundle with additional plugins"
parent: "bundle-global"
plugins:
  - "plugins.yaml"

bundle-2 includes a plugins.yaml file that contains an additional plugin that should be installed:

plugins:
  # In CAP
  - { id: "cloudbees-monitoring" }