Table of contents

CloudBees Jenkins Distribution installation guide

Installing on Kubernetes

CloudBees provides you a Helm chart to deploy CloudBees Jenkins Distribution on Kubernetes, making easier the installation.

This document explains the cluster requirements, points you to the cloud provider documentation needed to create a cluster, and explains how to install CloudBees Jenkins Distribution in your Kubernetes cluster.

The Kubernetes cluster requirements must be satisfied before CloudBees Jenkins Distribution can be installed as described in this chapter.

System and platform requirements

Refer to Supported platforms for CloudBees Jenkins Distribution for details about platforms supported for CloudBees Jenkins Distribution. This section provides details specific to installing on Kubernetes.

CloudBees Jenkins Distribution admin workstation

CloudBees Jenkins Distribution admin workstation is the computer used to install, update, and maintain CloudBees Jenkins Distribution. This workstation may be the workstation for the CloudBees Jenkins Distribution administrators or a Kubernetes administrator. In organizations that have several individuals performing CloudBees Jenkins Distribution administrator duties, it may be beneficial to use a bastion host instead of setting up a workstation for each CloudBees Jenkins Distribution administrator.

The requirements are:

  • Kubernetes Control client application,kubectl 1.x (starting with 1.11) must be installed and configured to work with your Kubernetes cluster.

  • The Helm client must be installed. Helm requirements are describe later in the Supported Helm section.

Supported Kubernetes

For CloudBees Jenkins Distribution, CloudBees supports Kubernetes 1.x, starting with 1.11, as long as it is actively supported by the Kubernetes distribution provider and is one of the following implementations:

  • Amazon EKS

    The version used must be Generally Available. CloudBees does not support or recommend "proof of concept" offering of Kubernetes platforms or Beta or Public preview versions.

    CloudBees Jenkins Distribution might work on other Kubernetes implementations such as Azure Kubernetes Service (AKS) or Google Kubernetes Engine (GKE) if it is installed as a Kubernetes Helm Chart, but CloudBees does not fully support these platforms. Red Hat OpenShift is not supported for the moment.

To create an Amazon Kubernetes cluster (EKS) refer to the official Amazon EKS documentation.

More information on Kubernetes concepts is available from the Kubernetes site, including:

Kubernetes cluster

CloudBees Jenkins Distribution must run on a Kubernetes cluster, and the cluster needs to meet these requirements:

  • A cluster running Kubernetes 1.x, starting with 1.11, as long as it is actively supported by the Kubernetes distribution provider and generally available.

    • With nodes that have at least 2 CPUs and 4 GBs of memory

    • Kubernetes cluster nodes in each availability zone

  • Network access to container images (public Docker Hub or a private Docker Registry)

  • A namespace in the cluster (provided by your Kubernetes admin) with permissions to create Role and RoleBinding objects

  • Access to the DNS record that points to your installation

  • SSL certificates (needed when you deploy CloudBees Jenkins Distribution)

    • If you are not planning to use this installation as a production environment, then you can install the default NGINX Ingress Controller without having TLS enabled. IMPORTANT: This means that only HTTP will be supported and not HTTPS.

    • For production environment usage, it is recommended that you installed your own NGINX Ingress controller and have your TLS certificates. Refer to NGINX Ingress controller section for further details.

  • A Default Storage Class defined and ready to use

    • kubectl get sc -o yaml | grep should return something.

Only production releases of Kubernetes and Helm are supported. You must use a production release.

Supported Helm

Only production releases of Helm are supported. You must use a production release.

  • The Helm client version 2.12 or higher installed locally.

  • If you want Helm to manage your application deployment, then the Tiller server 2.12 component must be installed in your Kubernetes cluster.

NGINX Ingress controller

CloudBees Jenkins Distribution requires an NGINX Ingress controller. The CloudBees Jenkins Distribution can utilize an existing NGINX Ingress Controller or you have the option to install a new NGINX Ingress controller as part of the CloudBees Jenkins Distribution Helm chart installation.

Using the Helm chart from CloudBees guarantees NGINX Ingress controller meets CloudBees Jenkins Distribution’s requirements. However, this automatic installation is quite simple. For a production environment, requiring TLS for example, you should create the NGINX Ingress Controller before installing CloudBees Jenkins Distribution Helm chart.

Please find the steps providing the recommended setup for NGINX Ingress Controller in CloudBees Core installation guide. Both installations share the same requirements and therefore the installation steps.

To customize the setup, please read the NGINX Ingress Controller Installation Guide for additional details.

Setting up Helm

Helm is a package manager for Kubernetes that manages an application’s dependencies, installation, and configuration. Helm manages the process of customizing an application to a specific environment. Helm dramatically simplifies installation, upgrades, rollbacks, and migrations.

Helm has two components: a Helm client and a server component, called Tiller. The Kubernetes administrator uses the Helm client to issue commands to the Tiller server.

A Helm installation is called a release. Helm can automatically create a release name. CloudBees recommends using a custom name such as cloudbees-jenkins-distribution during your initial install.

Every Helm command that is applied to the release is stored as a revision.

CloudBees recommends using Helm with the Tiller server-side component.

If you already have Helm client and Tiller server-side component installed, you can skip to the CloudBees Helm chart repository section.

Installing the Helm client

The Helm project readme provides detailed instructions on installing the Helm client on various operating systems in the installation section.

Please refer to this documentation to install the Helm client on your workstation.

Installing Tiller

Tiller is the Kubernetes cluster’s server-side component of Helm.

Use the following steps to install Tiller.

  1. Create a service account for Tiller

    kubectl create serviceaccount --namespace kube-system tiller
  2. Give that service account admin capabilities

    kubectl create clusterrolebinding tiller-cluster-rule --clusterrole=cluster-admin --serviceaccount=kube-system:tiller
  3. Install Tiller on Kubernetes cluster

    helm init --service-account tiller

Installing CloudBees Jenkins Distribution with Helm

CloudBees Helm chart repository

CloudBees hosts the Helm chart on CloudBees' public Helm chart repository. To access it, you need to add the repository to your Helm environment.

Adding CloudBees Helm chart repository

Helm support can use many public and private Helm chart repositories. Before you can use the CloudBees repository you must add it to your Helm environment with the helm repo add command.

Example 1. Adding CloudBees public Helm chart repository to your Helm environment
$ helm repo add cloudbees (1)
$ helm repo update (2)
  1. The helm repo add adds a new Helm chart repository to your Helm installation.

  2. The helm repo update updates your local Helm chart repository cache. Your local Helm chart repository cache is used by helm commands like helm search to improve performance.

Creating and use a namespace

CloudBees recommends using Kubernetes namespaces when you install CloudBees Jenkins Distribution. Combined with Kubernetes RBAC security, a Kubernetes administrator can restrict who has access to a namespace and its data.

Your Helm release name must be unique for the Kubernetes cluster, not just your namespace.
Example 2. Create a namespace, then set it as the current namespace
$ kubectl create namespace cloudbees-jenkins-distribution
$ kubectl config set-context $(kubectl config current-context) --namespace=cloudbees-jenkins-distribution

Performing a default installation

The default installation accepts all the default values CloudBees has defined and requires the NGINX Ingress controller. The CloudBees Jenkins Distribution Helm chart can install the NGINX Ingress controller, described in CloudBees Jenkins Distribution Installation with NGINX Controller.

Example 3. Default Helm installation
The helm install command
$ helm install --name cloudbees-jenkins-distribution \ (1) (2)
               --namespace cloudbees-jenkins-distribution \ (3)
  1. If you copy this command into your terminal don’t forget to remove the annotations at the end of each line.

  2. The name isn’t required, but without it Helm will automatically generate a release name with random strings. For this reason, CloudBees recommends always set a release name.

  3. Adding the --namespace argument instructs Helm to install everything in the cloudbees-jenkins-distribution namespace otherwise, it uses the currently selected namespace. Remember the namespace must already exist.

The command deploys cloudbees-jenkins-distribution on the Kubernetes cluster in the default configuration. The Configuration options section lists the parameters that can be configured during installation.

Installing CloudBees Jenkins Distribution with an NGINX Ingress controller

The chart is designed so it can install an NGINX Ingress controller. The nginx-ingress.enabled field controls if the Ingress controller has to be installed installation and setup. The example below illustrates how to install the chart with the release name cloudbees-jenkins-distribution and hostname

Example 4. Installing CloudBees Jenkins Distribution and an NGINX Ingress controller
$ helm install --name cloudbees-jenkins-distribution\ (1)
               --set nginx-ingress.enabled=true \ (2)
               --set master.serviceType='ClusterIP' \ (3)
               --namespace cloudbees-jenkins-distribution \ (4)
  1. Just like the previous example, the release name is set to cloudbees-jenkins-distribution.

  2. Setting nginx-ingress.enabled to true causes the CloudBees Jenkins Distribution Helm chart to also install a NGINX Ingress controller using the NGINX Ingress Helm chart.

  3. Since we want to use an ingress and the NGINX Ingress controller we need to use ClusterIP master.serviceType.

  4. Adding the --namespace argument instructs Helm to install everything in the cloudbees-jenkins-distribution namespace. Otherwise, it uses the currently selected namespace. Remember the namespace must already exist.

Using Custom Property Value files

Helm provides several ways to set value fields. The CloudBees Jenkins Distribution Helm chart provides CloudBees’s default values for CloudBees Jenkins Distribution. Helm stores these values in the chart’s values.yaml file. In the preceding sections, we’ve demonstrated overriding these fields on as helm install arguments using the --set parameter.

The final option is to create a custom YAML file containing value field assignments to override the default values set in the CloudBees Jenkins Distribution values.yaml file for your environment. CloudBees recommends creating a custom values file for your installation to keep all of your CloudBees Jenkins Distribution environment settings in your version control system to track of changes to the environment.

CloudBees recommends using a custom values file to upgrade and install CloudBees Jenkins Distribution using Helm.
Example 5. Example custom values file
helm install cloudbees/cloudbees-jenkins-distribution \
             --name cloudbees-jenkins-distribution \
             -f override-values.yaml \ (1)
  1. To use the custom value file with Helm, you use the -f argument with the custom value filename.

Upgrading CloudBees Jenkins Distribution using Helm

One of the key features of using Helm is the ease of upgrading and updating your CloudBees Jenkins Distribution release. The helm upgrade command allows you to upgrade your CloudBees Jenkins Distribution release. This can be new setting or a new version of CloudBees Jenkins Distribution.

Helm Issue 2948 and NGINX Ingress controller support

If you are using Installing CloudBees Jenkins Distribution with an NGINX Ingress controller option, you MUST set the nginx-ingress.enabled=true or the NGINX Controller will be deleted. For this reason, CloudBees strongly recommends you use a custom values file. For more details around Helm Issue 2948, see Helm Issue 2948 on GitHub.

This can be a new version of the CloudBees Jenkins Distribution Helm chart or an updated value you wish to apply to you release.

Example 6. Helm Example Values file
Helm upgrade command
helm upgrade -f upgrade-values.yaml --dry-run --debug (1) (2)
  1. Run the helm upgrade command with the -f argument to use the upgrade-value.yaml file Replace the examples-value.yaml filename with the name of your values file.

  2. Adding the --dry-run --debug run dry run of the installation without making changes.

Configuration options

The following tables lists the configurable parameters of the {JENKINS-DISTRI} chart and their default values. Many of them are based on the ones provided by the Jenkins OSS Helm chart and CloudBees provides recommended values for these options based on our experience.

Master configuration values

Table 1. Operations Center configurations values
Parameter Description Default


Override the resource name prefix



Override the full resource names

cloudbees-jenkins-distribution-{release-name} (or cloudbees-jenkins-distribution if release-name is cloudbees-jenkins-distribution or cjd)


Set number of executors



Administrator user of the CloudBees Jenkins Distribution instance



Initial admin user password. If the password isn’t set one will be automatically generated.

Autogenerated random value


Email address for the administrator of the CloudBees Jenkins Distribution instance

Not set


Aliases for IPs to add in Pod /etc/hosts



k8s service type



Service port for CloudBees Jenkins Distribution



Port where CloudBees Jenkins Distribution is running



Port where CloudBees Jenkins Distribution is accessible

Not set


Listening port for agents



Host port to listen for agents

Not set


Disabled agent protocols

JNLP-connect JNLP2-connect


Enable the default CSRF Crumb issuer



Some HTTP proxies filter out information that the default crumb issuer uses to calculate the nonce value. Seting a true value makes the nonce value easier to forge.



Enable CLI over remoting



Allowed inbound IP addresses. Only in case the serviceType is LoadBalancer. By default all IPs are allowed.


Open port for JMX stats

Not set


Open extra ports in the container running in the Pod if needed

Not set


Override config.xml, jenkins.CLI.xml, and jenkins.model.JenkinsLocationConfiguration.xml (only recommended for advanced admin users)



Set protocol to access CloudBees Jenkins Distribution as part of JENKINS_URL value

Set to https if Master.ingress.tls, http otherwise


List of scripts to execute during the initialization

Not set


Kubernetes secret that contains a credentials.xml file. Use only if credentials plugin is installed and only in upgrades.

Not set


secrets files to add to the instance

Not set


List of groovy functions to approve in case script-security plugin is installed. Use only to add new scripts in upgrades.

Not set


Set Affinity for preferred node selection. See Affinity in Kubernetes for further information.



Root Uri where CloudBees Jenkins Distribution will be served on. It is appended to JENKINS_URL.

Not set


The name of a priorityClass to apply to the master pod. See PriorityClass in Kubernetes for further information.

Not set

Agent values

Table 2. Agent Configurations Values
Parameter Description Default


Append Jenkins labels to the agent



Enable Kubernetes plugin jnlp-agent podTemplate



Agent image pull secret

Not set


Agent privileged container



Additional volumes

Not set


Environment variables for the Agent Pod

Not set


Executed command when side container starts

Not set


Arguments passed to executed command

Not set


Side container name in agent



Allocate pseudo tty to the side container



Maximum number of agent



Agent Pod base name

Not set


Allows the Pod to remain active for reuse



Table 3. Persistence Configuration Values
Parameter Description Default


Instead of creating a new Persistent Volumes Claim, the CloudBees Jenkins Distribution will use this existing Persistent Volumes Claim

Not Set


The size of the PVC



If defined, other volumes are mounted on the PVC

Not Set


If defined, other mount paths are mounted

Not Set

NGINX Ingress

The NGINX Ingress properties provided the option to install an NGINX Ingress controller. The default option of false, does not install the NGINX Ingress controller and will require an existing NGINX Ingress controller to be installed.

Table 4. NGINX Ingress configuration values
Parameter Description Default


Setting this property to true installs NGINX Ingress controller in addition to CloudBees Jenkins Distribution.



Ingress API version



Ingress host name

Not set


Ingress annotations



Ingress labels



Ingress path

Not set


Ingress TLS configuration



Enables openshift route



Route annotations



Route labels



Route path

Not set