How to install CloudBees Core on modern cloud platforms using Helm

Be sure that you have set up all the prerequisites before you install.
The supported Helm versions are listed in the Supported Platforms page.

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 Core using Helm, depending on your environment and needs. Select one of the following methods for installation.

Table 1. Helm installation methods
Method When to use it

Use Helm to install CloudBees Core 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 Core 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 Core 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.

Using Helm to install CloudBees Core with HTTP support

This is the default Helm method for installing CloudBees Core. It requires an NGINX Ingress Controller. If you do not already have a controller installed, the CloudBees Core Helm chart can install an NGINX Ingress Controller, as described in Installing CloudBees Core with an NGINX Ingress Controller.

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

This installation does the following:

  • Uses the default values specified by CloudBees.

  • Sets the OperationCenter.HostName field, if provided.

  • Installs the chart with the release name cloudbees-core.

  • Uses hostname cloudbees-core.example.com.

  • Uses the default storage class defined in the target cluster.

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

To use Helm to install CloudBees Core with HTTP support:

  1. Type the following commands:

$ helm install cloudbees-core \
               cloudbees/cloudbees-core \ (1)
               --namespace cloudbees-core \ (2)
               --set OperationsCenter.HostName='cloudbees-core.example.com' (3)
1 In this example, the command is using the CloudBees Helm chart repository. If you downloaded the CloudBees Core Helm chart from the CloudBees download site, replace cloudbees/cloudbees-core with cloudbees-core-helm-chart.tgz.
2 Adding 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.
3 OperationsCenter.HostName field is optional. If it is omitted, CloudBees Core uses Ingresses using wildcard hostnames and can be accessed through any hostname.

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

Using Helm to install CloudBees Core with HTTPS support

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

To use Helm to install CloudBees Core with HTTPS support:

  1. Type the follow command to create a new Kubernetes certificate secret:

kubectl create secret tls cloudbees-core-example-com-tls \ (1)
        --key /etc/letsencrypt/live/example.com/privkey.pem \ (2)
        --cert /etc/letsencrypt/live/example.com/fullchain.pem \ (3)
        --namespace cloudbees-core (4)
1 You are creating a new TLS secret with the name cloudbees-core-example-com-tls, which is the CloudBees Core Helm default TLS secret name. If you want to change this name, you need to also update OperationsCenter.Ingress.tls.SecretName with your secret name.
2 Use your key file.
3 Use your certificate.
4 The secret should be in the same namespace as the pod that will use it. You can ensure this by using the --namespace argument. CloudBees recommends working within the namespace.
  1. Type the following command to set the OperationsCenter.Ingress.tls.Enable to true:

$ helm install cloudbees-core \
               cloudbees/cloudbees-core \
               --namespace cloudbees-core \ (1)
               --set OperationsCenter.HostName='cloudbees-core.example.com' \ (2)
               --set OperationsCenter.Ingress.tls.Enable=true \ (3)
               --set OperationsCenter.Ingress.tls.SecretName='cloudbees-core-example-com-tls' (4)
1 Adding 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.
2 Replace cloudbees-core.example.com domain name with your domain name.
3 The property OperationsCenter.Ingress.tls.Enable=true enables CloudBees Core TLS support at Ingress level.
4 You need to set OperationsCenter.Ingress.tls.SecretName with your secret name.

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

Using Helm to install CloudBees Core 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. Type 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)
1 In this example, the command uses the CloudBees Helm chart repository. If you are using the CloudBees Core Helm archive package included in the CloudBees Core installation package, replace this argument with the CloudBees Core Helm archive package filename.
2 Adding 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.
3 Replace cloudbees-core.example.com domain name with your domain name.
4 Setting nginx-ingress.Enabled to true causes the CloudBees Core 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 Core, you should verify that it is installed correctly.

Using a custom YAML file to install CloudBees Core

Custom values files are Helm configuration parameters stored in a YAML file that overrides the CloudBees Core chart’s values.yaml file’s default values. This YAML file provides a more managed approach instead of passing custom values using the Helm client --set parameter. This custom values file can be checked into a source control management (SCM) system for version control.

By using the custom values YAML file, you can 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 Core, because you can compare each change to the previous version to rapidly identify problems.

To install using a custom value YAML file:

  1. Type the following commands:

helm install cloudbees-core \
             cloudbees/cloudbees-core \
             --namespace cloudbees-core \ (1)
             --values example-values.yaml (2)
1 --namespace=cloudbees-core instructs Helm to install everything in the cloudbees-core namespace. Otherwise, it uses the currently selected namespace. If you’re creating the YAML file in your desired namespace, this argument is not needed.
2 --values example-values.yaml instructs Helm to use the custom value file.

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

Example custom YAML file

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

The example-values.yaml file is explained below.

# A helm example values file for standard kubernetes install.
# An nginx-ingress controller is not installed and ssl isn't installed.
# Install an nginx-ingress controller
 nginx-ingress:
   Enabled: false (1)

 OperationsCenter:
   # Set the HostName for the Operation Center
   HostName: 'cloudbees-core.example.com' (2)
   # Setting ServiceType to ClusterIP creates ingress
   ServiceType: ClusterIP
   Ingress:
     tls:
     ## Set this to true in order to enable TLS on the ingress record
       Enable: false (3)
       # Create a certificate kubernetes and use it here.
       SecretName: core-example-com-tls
       Host: jenkins.cluster.local
1 Setting Enabled here is the same as using --set nginx-ingress.Enabled=true on the command line, as discussed in Installing CloudBees Core with an NGINX Ingress Controller.
2 These properties are the same as:
  • OperationsCenter.HostName

  • OperationsCenter.Ingress.tls.Enable

  • OperationsCenter.Ingress.tls.SecretName

3 This enables TLS on the Ingress record.

Example migration custom values file

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

# A helm example values file for migrating a CloudBees Core for Modern Platform Install.
# Install an nginx-ingress controller
nginx-ingress:
  Enabled: false (1)

OperationsCenter:
  # Set the HostName for the Operation Center
  HostName: 'cloudbees-core.example.com' (2)
  Ingress:
    tls:
    ## Set this to true in order to enable TLS on the ingress record
      Enable: false (3)
      SecretName: core-example-com-tls
      Host: jenkins.cluster.local

# If you are migrating from an existing manual installation of CloudBees Core, provide the PVC that was created
# during the initial installation
Persistence:
  ExistingClaim: 'jenkins-home-cjoc-0' (4)
1 If you want NGINX Ingress Controller installed, change this value to true.
2 Replace cloudbees-core.example.com domain name with your domain name.
3 If you want to enable TLS, set this value to true.
4 jenkins-home-cjoc-0 is the PVC that is created using CloudBees Core, so keep this value.

Using the Helm template command to install CloudBees Core

Customers who do not wish to use the helm install method can use helm template method, which will process the template and generate the Kubernetes resources.

This can be used to install a new version of the CloudBees Core Helm chart or to update a value that you wish to apply to your release.

To use the Helm template command to install CloudBees Core:

  1. Type the following command:

helm fetch cloudbees/cloudbees-core \
           --version 12345 (1)
1 Replace 12345 with the chart version. You can retrieve the chart version you need for a given version of CloudBees Core by running helm search repo -l cloudbees/cloudbees-core. The --version flag is optional, skip it to use the latest chart version available.
  1. Type the following commands:

helm template cloudbees-core \ (1)
              cloudbees-core-helm-chart.tgz \ (2)
              --values example-values.yaml \ (3)
              --namespace {namespace} \ (4)
              > cloudbees-core.yaml (5)
1 Replace cloudbees-core with the release name you used in your CloudBees Core installation.
2 Replace cloudbees-core-helm-chart.tgz with the archive that was downloaded by helm fetch in the previous step.
3 Run the helm template command with the --values argument to use the examples-value.yaml file. Replace the examples-value.yaml filename with the name of your values file.
4 Adding 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.
5 cloudbees-core.yaml is the YAML file that is created by helm-template via Linux file redirect. Once this custom YAML has been created, you can use kubectl apply to install CloudBees Core.
  1. Type the following command:

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

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

example-values.yaml

# A helm example values file for standard kubernetes install.
# An nginx-ingress controller is not installed and ssl isn't installed.
# Install an nginx-ingress controller
nginx-ingress:
  Enabled: false (1)

OperationsCenter:
  # Set the HostName for the Operation Center
  HostName: 'cloudbees-core.example.com' (2)
  Ingress:
    tls:
    ## Set this to true in order to enable TLS on the ingress record
      Enable: false  (3)
      SecretName: core-example-com-tls
      Host: jenkins.cluster.local
1 If you want the NGINX Ingress Controller installed, change this value to true.
2 Replace cloudbees-core.example.com with your domain name.
3 If you want to enable TLS, set this value to true.

Verifying your CloudBees Core installation using helm status

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

The helm status command displays the status of the CloudBees Core 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 Core release

  • Kubernetes resources

  • 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
1 The first block provides a summary of the CloudBees Core release including:
  • Name of the release

  • The time released

  • The status of the release and

  • The namespace the release is installed in

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

Logging in to your CloudBees Core installation

Now that you’ve installed CloudBees Core and Operations Center, you’ll want to see your system in action.

  1. Type the following command to retrieve your administrative user password:

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

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

For more information on running CloudBees Core on Kubernetes, see the CloudBees Core on modern cloud platforms administration guide.

Using self-signed certificates

If you need access to resources using a corporate self-signed Certificate Authority (CA), read this article.