CloudBees no longer supports CloudBees Jenkins Distribution as of February 24, 2021. Please refer to the following step-by-step documentation for Migrating from CloudBees Jenkins Distribution to Jenkins LTS. The increased alignment between CloudBees Jenkins Distribution and Jenkins means users will experience zero impact to Pipeline execution. Existing customers can also contact CloudBees Support to help ensure a smooth transition.
Please see About the CloudBees Jenkins Distribution retirement for more information.
CloudBees simplifies the installation of CloudBees Jenkins Distribution on Kubernetes by providing you with a Helm chart.
At a minimum, the Kubernetes cluster requirements must be satisfied before CloudBees Jenkins Distribution can be installed.
CloudBees Jenkins Distribution is supported only on production releases of Kubernetes and Helm.
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.
The 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 for the admin workstation are:
kubectlKubernetes Control client application, version 1.11 or greater, installed and configured to work with your Kubernetes cluster.
The Helm client. Helm requirements are described later in the Helm section.
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:
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.
CloudBees only supports CloudBees Jenkins Distribution on Kubernetes when it is installed using the official CloudBees Jenkins Distribution Helm charts.
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:
CloudBees Jenkins Distribution must run on a Kubernetes cluster, and the cluster must meet these requirements:
A production release of Kubernetes 1.11 or greater, 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
Access to the DNS record that points to your installation.
SSL certificates (needed when you deploy CloudBees Jenkins Distribution):
For production environments, install your own NGINX Ingress controller and obtain TLS certificates. Refer to NGINX Ingress controller section for further details.
If you are not planning to use this installation as a production environment, you can install the default NGINX Ingress Controller without enabling TLS. However, this means that only HTTP will be supported and not HTTPS.
A Default Storage Class defined and ready to use
To identify your default storage class, use the
kubectl get sc -o yaml | grep storageclass.beta.kubernetes.io/is-default-classcommand.
CloudBees supports only production releases of Helm: RC, beta, patch or experimental releases of Helm are not supported.
Starting with CloudBees CI on modern cloud platforms version 188.8.131.52, Helm version 3.0.2 or later is supported.
We recommend that you migrate to Helm V3 as soon as possible. Support of Helm V2 was deprecated in July 2020.
CloudBees Jenkins Distribution requires an NGINX Ingress controller. CloudBees Jenkins Distribution can either use an existing NGINX Ingress Controller or you can install an NGINX Ingress Controller as part of the Helm chart installation process.
|Although the NGINX Ingress Controller installed with the Helm chart meets CloudBees Jenkins Distribution requirements, it is not ideal for a production environment; if you are operating a production environment that requires TLS, you should create the NGINX Ingress Controller before installing the Helm chart.|
+ Instructions for installing the NGINX Ingress Controller are given in Installing CloudBees CI on Amazon Elastic Kubernetes Service (Amazon EKS), and the NGINX Ingress Controller Installation Guide gives instructions for customizing the installation.
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 and dramatically simplifies installation, upgrades, rollbacks, and migrations.
|If you already have Helm client and Tiller server-side component installed, you can skip to the CloudBees Helm chart repository section.|
Helm has two components: * A Helm client. * 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.
Tiller is the Kubernetes cluster’s server-side component of Helm.
Use the following steps to install Tiller.
Create a service account for Tiller:
shell% kubectl create serviceaccount --namespace kube-system tiller
Give the service account administrative capabilities:
shell% kubectl create clusterrolebinding tiller-cluster-rule --clusterrole=cluster-admin --serviceaccount=kube-system:tiller
Install Tiller on the Kubernetes cluster:
shell% helm init --service-account tiller
CloudBees hosts the Helm chart on CloudBees' public Helm chart repository. To access it, you need to add the repository to your Helm environment.
Add the CloudBees Helm chart to your Helm environment with the
helm repo add command:
$ helm repo add cloudbees https://charts.cloudbees.com/public/cloudbees (1) $ helm repo update (2)
CloudBees recommends using Kubernetes namespaces to install CloudBees Jenkins Distribution.
Combining Kubernetes RBAC security with a namespace allows a Kubernetes administrator to 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.|
To create a namespace:
shell% kubectl create namespace cloudbees-jenkins-distribution shell% kubectl config set-context $(kubectl config current-context) --namespace=cloudbees-jenkins-distribution
The default installation accepts all the default values CloudBees has defined and requires the NGINX Ingress controller:
shell% helm install --name cloudbees-jenkins-distribution \ (1) (2) --namespace cloudbees-jenkins-distribution \ (3) cloudbees/cloudbees-jenkins-distribution
|1||If you copy this command into your terminal don’t forget to remove the annotations at the end of each line.|
|3||Adding the |
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.
The chart is designed so it can install an NGINX Ingress controller.
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
$ helm install --name cloudbees-jenkins-distribution\ (1) --set nginx-ingress.enabled=true \ (2) --set master.serviceType='ClusterIP' \ (3) --namespace cloudbees-jenkins-distribution \ (4) cloudbees/cloudbees-jenkins-distribution
|1||Just like the previous example, the release name is set to |
|3||Since we want to use an ingress and the NGINX Ingress controller we need to use |
|4||Adding the |
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
In the preceding sections, we’ve demonstrated overriding these fields on as
helm install arguments using the
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.|
helm install cloudbees/cloudbees-jenkins-distribution \ --name cloudbees-jenkins-distribution \ -f override-values.yaml \ (1) --namespace=cloudbees-jenkins-distribution
|1||To use the custom value file with Helm, you use the |
One of the key features of using Helm is the ease of upgrading and updating your CloudBees Jenkins Distribution release.
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
This can be a new version of the CloudBees Jenkins Distribution Helm chart or an updated value you wish to apply to you release.
helm upgrade -f upgrade-values.yaml --dry-run --debug (1) (2)
|1||Run the |
|2||Adding the |
The following tables lists the configurable parameters of the CloudBees Jenkins Distribution 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.
Override the resource name prefix
Override the full resource names
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
Aliases for IPs to add in Pod
k8s service type
Service port for CloudBees Jenkins Distribution
Port where CloudBees Jenkins Distribution is running
Port where CloudBees Jenkins Distribution is accessible
Listening port for agents
Host port to listen for agents
Disabled agent protocols
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
Open extra ports in the container running in the Pod if needed
Set protocol to access CloudBees Jenkins Distribution as part of JENKINS_URL value
List of scripts to execute during the initialization
Kubernetes secret that contains a
List of groovy functions to approve in case script-security plugin is installed. Use only to add new scripts in upgrades.
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.
The name of a
Append Jenkins labels to the agent
Enable Kubernetes plugin jnlp-agent podTemplate
Agent image pull secret
Agent privileged container
Environment variables for the Agent Pod
Executed command when side container starts
Arguments passed to executed command
Side container name in agent
Allocate pseudo tty to the side container
Maximum number of agent
Agent Pod base name
Allows the Pod to remain active for reuse
Instead of creating a new Persistent Volumes Claim, the CloudBees Jenkins Distribution will use this existing Persistent Volumes Claim
The size of the PVC
If defined, other volumes are mounted on the PVC
If defined, other mount paths are mounted
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.
Setting this property to true installs NGINX Ingress controller in addition to CloudBees Jenkins Distribution.
Ingress API version
Ingress host name
Ingress TLS configuration
Enables openshift route