How to install CloudBees CI on modern cloud platforms on OpenShift using Helm

10 minute read

After you have set up the prerequisites, use the following steps to ensure the installation is successful:

Choosing the right Helm installation method

You can use one of several methods to install CloudBees CI using Helm, depending on your environment and needs. Select one of the following methods for installation.

The supported Helm versions are listed in the Supported Platforms page.
Table 1. Helm installation methods
MethodWhen to use it

Use Helm to install CloudBees CI with HTTP support

This is the default installation method. Use it if you already have an NGINX Ingress Controller installed and you need HTTP support.

Use Helm to install CloudBees CI with HTTPS support

Use this method if you already have an NGINX Ingress Controller installed and you need HTTPS support.

Use Helm to install CloudBees CI and an NGINX Ingress Controller

Use this method if you do not already have an NGINX Ingress Controller installed.

Use a custom value YAML file

Use this if you want to use a custom value YAML file.

Use the Helm template command

Use this method if you don’t want to manage releases using Helm.

Installation via the CloudBees installer has been deprecated as of the release of CloudBees CI on modern cloud platforms 2.204.3.4.

Using Helm to install CloudBees CI with HTTP support

This is the default Helm method for installing CloudBees CI.

The default installation does the following:

  • Uses the default values specified by CloudBees.

  • Sets the OperationCenter.HostName field.

  • Installs the chart with the release name cloudbees-core and hostname cloudbees-core.example.com.

  • Deploys cloudbees-core on the OpenShift cluster in the default configuration.

This method supports HTTP. If you require HTTPS support, you should follow the procedure for using Helm to install CloudBees CI with HTTPS support.

Fields are case-sensitve: OperationsCenter.HostName is different than operationcenter.hostname.

To use Helm to install CloudBees CI with HTTP support:

$ helm install cloudbees-core \ # Invalid code tag detected: 1
1If you copy this command into your terminal don’t forget to remove the annotations at the end of each line.
2The 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.
3In this example, the command is using the CloudBees Helm Chart Repository.
4OperationsCenter.HostName field is required. The CloudBees CI Helm chart will not install without a HostName being provided.
5OperationsCenter.Project.name is the OpenShift project.

After you have installed CloudBees CI, you should verify that it is installed correctly.

Using Helm to install CloudBees CI with HTTPS support

By default, the CloudBees CI Helm chart uses HTTP. To use HTTPS, you must enable the TLS support and provide your TLS certificate.

  1. First, create a new OpenShift TLS certificate secret. For instructions, see the Secrets chapter of the Red Hat OpenShift documentation.

  2. Once an OpenShift certificate secret has been created, you can use the Helm chart to install CloudBees CI with SSL\TLS support by setting OperationsCenter.Ingress.tls.Enable to true.

$ helm install cloudbees-core \
               cloudbees/cloudbees-core \
               --set OperationsCenter.HostName='cloudbees-core.example.com' \
               --set OperationsCenter.Route.tls.Enable=true \ Invalid code tag detected: 1
1Here, you are setting OperationsCenter.Route.tls.Enable to true. This property turns on CloudBees CI HTTPS support.
2OperationsCenter.Project.name is the OpenShift project.

After you have installed CloudBees CI, you should verify that it is installed correctly.

Using Helm to install CloudBees CI and an NGINX Ingress Controller

The Helm chart can install an NGINX Ingress Controller as part of its own installation.

The nginx.ingress.enabled field controls Ingress Controller installation and setup.

  1. Enter the following command to install the Helm chart with the release name cloudbees-core and hostname cloudbees-core.example.com:

$ helm install cloudbees-core \
               cloudbees/cloudbees-core \ (1)
               --namespace cloudbees-core \ (2)
               --set OperationsCenter.HostName='cloudbees-core.example.com' \ (3)
               --set nginx-ingress.Enabled=true (4)
1In this example, the command uses the CloudBees Helm chart repository. If you are using the CloudBees CI Helm archive package included in the CloudBees CI installation package, replace this argument with the CloudBees CI Helm archive package filename.
2Adding the --namespace argument instructs Helm to install everything in the cloudbees-core namespace. Otherwise, it uses the currently selected namespace. If you are already in your desired namespace, this argument is not needed. Remember the namespace must already exist.
3Replace cloudbees-core.example.com domain name with your domain name.
4Setting nginx-ingress.Enabled to true causes the CloudBees CI Helm chart to also install an NGINX Ingress Controller using the NGINX Ingress Helm chart. Once the ingress controller is installed, you will need to configure a DNS entry to target the corresponding external IP or hostname.

After you have installed CloudBees CI, you should verify that it is installed correctly.

Using a custom value YAML file to install CloudBees CI

Custom values files are Helm configuration parameters stored in a YAML file that overrides the CloudBees CI chart’s values.yaml file default values. This is a more maintainable approach than passing several custom values using the Helm client --set parameter. This YAML file can be checked into a Source Control Management (SCM) system, which means you don’t have to recall all the command-line settings, options, and parameters you used each time you upgrade.

You can then more easily delegate upgrades to other team members, review the configuration settings in the SCM, and follow standard DevOps practices like code review for configuration changes. Finally, you gain an audit trail for changes to CloudBees CI, because you can compare each change to the previous version to rapidly identify problems.

For more detail on GitOps, see the CloudBees Blog entry GitOps: Dev, with a Dash of Ops!.

To install using a custom value YAML file:

helm install cloudbees/cloudbees-core --name cloudbees-core -f example-values.yaml

-f example-values.yaml instructs Helm to use the custom value file.

Example custom YAML file

CloudBees provides a number of sample custom value files in the cloudbees-examples GitHub repository.

The openshift-example-values.yaml file is explained below.

# A helm example values file for standard openshift install.

 OperationsCenter:
   # Set the HostName for the Operation Center
   HostName: 'cloudbees-core.example.com' # Invalid code tag detected: 2
1These properties are the same as:
  • OperationsCenter.HostName

  • OperationsCenter.Route.tls.Enable

  • OperationsCenter.Route.tls.SecretName

2This enables TLS on the Route.

Example migration custom values file

The following custom values file is based on the openshift-example.yaml file from the CloudBees Public GitHub repository.

The openshift-example.yaml file is explained below.

# A helm example values file for an OpenShift install
# Install an nginx-ingress controller
  nginx-ingress:
      Enabled: false
  OperationsCenter:
    # Set the platform to openshift, so that routes are created
    Platform: 'openshift'
    # Set the HostName for the Operation Center
    HostName: 'cloudbees-core.example.com'
    # Setting ServiceType to ClusterIP creates ingress
    ServiceType: ClusterIP
    Route:
      tls:
        ## Set this to true in order to enable TLS on the ingress route
        Enable: false
        ## Replace with your Kubernetes Certificate Select
        SecretName: core-example-com-tls
    # Update this with the openshift project your are using.
    Project:
      name: myproject

Helm configuration values

The following table lists the configurable parameters of the CloudBees CI chart and their default values. Each property can overridden in an environment specific or on the Helm command line.

The CloudBees CI Helm chart includes some additional properties, not documented here, that may be visible to you as a Kubernetes administrator. Changing properties that are not explicitly documented here can destabilize your installation or cause data loss.

Operations Center Configuration Values

The following properties manage the Operation Center installation and operation. CloudBees provides recommended values for these options based on our experience of helping hundreds of customers utilize Jenkins or CloudBees CI.

Table 2. Operations Center Configurations Values
ParameterDescriptionDefault

OperationsCenter.Name

CloudBees Operation Center server name

cjoc

OperationsCenter.HostName

REQUIRED CloudBees Operation Center HostName.

cloudbees-core.example.com

OperationsCenter.Image.dockerImage

Operation Center’s Docker image

cloudbees/cloudbees-core-oc:2.176.1.4

OperationsCenter.Image.dockerPullPolicy

Operation Center’s Docker image pull policy

Always

OperationsCenter.Image.pullSecret

Operation Center’s Docker image pull secret

Not set

OperationsCenter.ServiceAnnotations

Service annotations for the Operations Center service

Not Set

OperationsCenter.HealthProbes

Enables Kubernetes Liveness and Readiness Probes

true

OperationsCenter.HealthProbesTimeout

Operations Center Health Probe Timeout. This is set to approximately two minutes to allow Operations Center to restart when upgrading plugins.

300

OperationsCenter.HealthLivenessFailureThreshold

Sets the failure threshold for the liveness probe

12

OperationsCenter.CSRF.ProxyCompatibility

Enable default CSRF crumb issuer with proxy compatibility.

Not Set

OperationsCenter.JavaOpts

Adds additional Java option to be used when Operation Center starts up. For example, setting up a JMX port.

Not Set

OperationsCenter.NodeSelector

Node labels for pod assignment. This is an advanced Kubernetes feature. For more information, see the nodeSelector section of the Kubernetes documentation.

Not Set

OperationsCenter.Tolerations

This is an advanced Kubernetes feature. For more information, see the Taints and tolerations section of the Kubernetes documentation.

Not Set

Master Configuration Values

The following properties manage which Docker Image is used in the creation of the Managed Master.

Table 3. Managed Master Configurations Values
ParameterDescriptionDefault

Master.Name

Jenkins master name

jenkins-master

Master.Image

Managed Master Docker image

cloudbees/cloudbees-core-mm

Master.Image.dockerImageTag

Managed Master Docker image tag

2.176.1.4

Master.Image.dockerPullPolicy

Managed Master Docker image pull policy

Always

Master.Image.longName

Managed Master Name displayed in the CloudBees CI User Interface.

CloudBees CI - Managed Master - 2.176.1.4

NGINX Ingress configuration values

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.

ParameterDescriptionDefault

nginx-ingress.Enabled

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

false

Persistence

Persistent properties allow the use of alternative storage classes and reusing an existing Persistent Volumes Claim. For more information, see Migrating CloudBees CI instances on Kubernetes to Helm for AKS, EKS, GKE, PKS, or generic Kubernetes, or see Migrating CloudBees CI instances on Openshift to Helm for OpenShift.

Table 4. Persistence Configuration Values
ParameterDescriptionDefault

Persistence.ExistingClaim

Instead of creating a new Persistent Volumes Claim, the Operation Center will use this existing Persistent Volumes Claim

Not Set

Persistence.StorageClass

If undefined, the default, the provisioner will use the default storageClassName. On AWS gp2 is used.

Not Set

After you have installed CloudBees CI, you should verify that it is installed correctly.

Using the helm template command to install CloudBees CI

Customers who do not wish to use or cannot use a public Helm chart server can use the helm template method.

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

helm template cloudbees-core \ # Invalid code tag detected: 1
1Replace cloudbees-core with the release name you used in you CloudBees CI installation.
2This indicates you are generating output targeted for OpenShift, which generates OpenShift-specific resources such as routes.
3Run the helm template command with the -f argument to use the examples-value.yaml file.

Replace the examples-value.yaml filename with the name of your values file. Replace this with the compressed Helm chart for the installation package.

4cloudbees-core.yml is the YAML file that is created by helm-template via Linux file redirect.

example-values.yaml

OperationsCenter:
  # Set the HostName for the Operation Center
  HostName: 'cloudbees-core.example.com' # Invalid code tag detected: 1
1Replace cloudbees-core.example.com with your domain name.
2If you want to enable TLS, set this value to true.
3myproject is the OpenShift project.

Customizing a value in a Helm template

To customize a value in a template:

  1. Locate the template you want to customize.

  2. Find the name of the value to modify in this template.

The following example shows how to customize the JAVA_OPTS of the Operation Center:

  • This value is set to StatefulSet for operations center. To locate the template, from the Helm chart archive, under the templates directory, search for`cjoc-statefulset.yaml`

  • In the template, look for the JAVA_OPTS to find the value to customize:

{{- if .Values.OperationsCenter.JavaOpts }}
{{ .Values.OperationsCenter.JavaOpts }}
{{- end }}

From Values.OperationsCenter.JavaOpts, you can derive the value file to write.

Note that the Hostname value is also passed as it is a mandatory field:

OperationsCenter:
  HostName: 'cloudbees-core.example.com'
  JavaOpts: '-Dmy.additional.option=true'

Installing CloudBees CI from the custom YAML file

Once this custom YAML has been created you can use oc apply to install CloudBees CI:

$ oc apply -f cloudbees-core.yml (1)
1Replace cloudbees-core.yml with the name of your custom YAML file.

After you have installed CloudBees CI, you should verify that it is installed correctly.

Verifying the installation using helm status

Once the CloudBees CI Helm install is initiated, Helm displays the status of release.

The helm status command displays the status of the CloudBees CI release. This command is also executed after helm install and helm update commands are executed.

The helm status command displays three areas of information:

  • Current CloudBees CI Release

  • Kubernetes Resoures

  • Release Notes

$ helm status
NAME:   cloudbees-core (1)
LAST DEPLOYED: Tue Apr 16 17:44:12 2019 (1)
NAMESPACE: default (1)
STATUS: DEPLOYED (1)

RESOURCES: (2)
==> v1/ConfigMap
NAME                                        DATA  AGE
cloudbees-core-configure-jenkins-groovy     1     1s
cloudbees-core-nginx-ingress-controller     1     1s
jenkins-agent                               1     1s

==> v1/Pod(related)
NAME                                                             READY  STATUS             RESTARTS  AGE
cloudbees-core-0                                              0/1    Pending            0         0s
cloudbees-core-nginx-ingress-controller-69b4cc776f-p8jtr      0/1    ContainerCreating  0         0s
cloudbees-core-nginx-ingress-default-backend-5649b4d6bc2vqhd  0/1    ContainerCreating  0         0s

==> v1/Role
NAME                                 AGE
cloudbees-core-agents             1s
cloudbees-core-master-management  1s

==> v1/RoleBinding
NAME                                   AGE
cloudbees-core-master-role-binding  1s
cloudbees-core-role-binding         1s

==> v1/Service
NAME                                             TYPE          CLUSTER-IP      EXTERNAL-IP  PORT(S)                       AGE
cloudbees-core                                LoadBalancer  10.100.48.73    <pending>    80:31632/TCP,50000:30068/TCP  0s
cloudbees-core-nginx-ingress-controller       LoadBalancer  10.100.209.210  <pending>    80:31100/TCP,443:32755/TCP    0s
cloudbees-core-nginx-ingress-default-backend  ClusterIP     10.100.113.103  <none>       80/TCP                        0s

==> v1/ServiceAccount
NAME                             SECRETS  AGE
cloudbees-core-cjoc-sa        1        1s
cloudbees-core-master-sa      1        1s
cloudbees-core-nginx-ingress  1        1s

==> v1/StatefulSet
NAME               READY  AGE
cloudbees-core  0/1    0s

==> v1beta1/ClusterRole
NAME                             AGE
cloudbees-core-nginx-ingress  1s

==> v1beta1/ClusterRoleBinding
NAME                             AGE
cloudbees-core-nginx-ingress  1s

==> v1beta1/Deployment
NAME                                             READY  UP-TO-DATE  AVAILABLE  AGE
cloudbees-core-nginx-ingress-controller       0/1    1           0          0s
cloudbees-core-nginx-ingress-default-backend  0/1    1           0          0s

==> v1beta1/PodDisruptionBudget
NAME                                             MIN AVAILABLE  MAX UNAVAILABLE  ALLOWED DISRUPTIONS  AGE
cloudbees-core-nginx-ingress-controller       1              N/A              0                    1s
cloudbees-core-nginx-ingress-default-backend  1              N/A              0                    1s

==> v1beta1/Role
NAME                             AGE
cloudbees-core-nginx-ingress  1s

==> v1beta1/RoleBinding
NAME                             AGE
cloudbees-core-nginx-ingress  1s
1The first block provides a summary of the CloudBees CI release including:
  • Name of the release

  • The time released

  • The status of the release and

  • The namespace the release is installed in.

2The Resource section shows all the Kubernetes resources that were created by this release.

Signing in to your CloudBees CI installation

Now that you’ve installed CloudBees CI and operations center, you’ll want to see your system in action.

  1. Retrieve your administrative user password with the oc command:

    $ oc exec cloudbees-core-0 cat /var/jenkins_home/secrets/initialAdminPassword
  2. Open a browser client and navigate to http://cloudbees-core.example.com/cjoc/.

  3. Sign in with the username admin and the password you retrieved.

  4. Configure the OpenShift plugin in Jenkins to use the cloudbees-core Service Account name:

    1. Create a Jenkins credential of the type Kubernetes service account with the service account name cloudbees-core.

    2. Under configure Jenkins, update the credentials config in the cloud section to use the service account credential you created in the step above.