Installing CloudBees CI on modern cloud platforms on EKS

8 minute read

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:

Installation options

CloudBees provides different installation instructions for different installation scenarios. Use the table below to help you determine the best option for your environment.

Table 1. Installation options
OptionUse it when

With the default values

You already have an NGINX Ingress Controller installed and you want to use the default installation values.

With HTTPS support

You already have an NGINX Ingress Controller installed and you need HTTPS support. NOTE: HTTPS is highly recommended for production use.

With an NGINX Ingress Controller

You do not already have an NGINX Ingress Controller installed.

Using a custom value YAML file

You want to use a custom value YAML file. The 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.

Using the Helm template command

You don’t want to manage releases using Helm.

Installing CloudBees CI with the default values

This is the default CloudBees CI installation. It requires an NGINX Ingress Controller. If you do not already have a controller installed, the CloudBees CI Helm chart can install an NGINX Ingress Controller, as described in Installing CloudBees CI 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 CI 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 install CloudBees CI with the default values:

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

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

Installing 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 before you install.

To install CloudBees CI 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)
1You are creating a new TLS secret with the name cloudbees-core-example-com-tls, which is the CloudBees CI 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.
2Use your key file.
3Use your certificate. fullchain.pem should start with your certificate (-----BEGIN CERTIFICATE-----…​-----END CERTIFICATE-----), followed by any intermediate certificates. The order is important. Each intermediate certificate should be on its own line in the file, and also have the same header -----BEGIN CERTIFICATE-----…​-----END CERTIFICATE-----. Do not change the headers to try to comment which one is an intermediate certificate.
4The 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)
1Adding 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.
2Replace cloudbees-core.example.com domain name with your domain name.
3The property OperationsCenter.Ingress.tls.Enable=true enables CloudBees CI TLS support at Ingress level.
4You need to set OperationsCenter.Ingress.tls.SecretName with your secret name.

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

Installing CloudBees CI with an NGINX Ingress Controller

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

The ingress-nginx.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 ingress-nginx.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 ingress-nginx.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.

Installing CloudBees CI using a custom YAML file

Custom values files are Helm configuration parameters stored in a YAML file that overrides the CloudBees CI 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 CI, 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 CI, 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
 ingress-nginx:
   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
1Setting Enabled here is the same as using --set ingress-nginx.Enabled=true on the command line, as discussed in Installing CloudBees CI with an NGINX Ingress Controller.
2These properties are the same as:
  • OperationsCenter.HostName

  • OperationsCenter.Ingress.tls.Enable

  • OperationsCenter.Ingress.tls.SecretName

3This 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 CI on modern cloud platforms installation.
# Install an NGINX Ingress Controller
ingress-nginx:
  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

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

Installing CloudBees CI using the Helm template command

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 CI Helm chart or to update a value that you wish to apply to your release.

To use the Helm template command to install CloudBees CI:

  1. Type the following command:

helm fetch cloudbees/cloudbees-core \
           --version 12345 (1)
1Replace 12345 with the chart version.You can retrieve the chart version you need for a given version of CloudBees CI 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 cloudbees-core \ (4)
              > cloudbees-core.yaml (5)
1Replace cloudbees-core with the release name you used in your CloudBees CI installation.
2Replace cloudbees-core-helm-chart.tgz with the archive that was downloaded by helm fetch in the previous step.
3Run 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.
4Adding 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.
5cloudbees-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 CI.
  1. Type the following command:

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

After you have installed CloudBees CI, 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
ingress-nginx:
  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
1If you want the NGINX Ingress Controller installed, change this value to true.
2Replace cloudbees-core.example.com with your domain name.
3If you want to enable TLS, set this value to true.

Verifying your CloudBees CI installation

Once the CloudBees CI Helm install is initiated, Helm displays the status of the 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 resources

  • Release notes

$ helm status cloudbees-core
NAME:   cloudbees-core (1)
LAST DEPLOYED: Tue Apr 16 17:44:12 2019 (1)
NAMESPACE: default (1)
STATUS: DEPLOYED (1)
REVISION: 1
TEST SUITE: None
NOTES:
1. Once {OC} is up and running, get your initial admin user password by running:
  kubectl rollout status sts cjoc --namespace cloudbees-core
  kubectl exec cjoc-0 --namespace cloudbees-core -- cat /var/jenkins_home/secrets/initialAdminPassword
2. Visit https://cloudbees-core.acme.com/cjoc/


3. Login with the password from step 1.

For more information on running {CI-CLOUD}, visit:
xref:cloudbees-ci:ROOT:index.adoc[CloudBees CI]
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

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. 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. Sign in with the username admin and the password you retrieved.

For more information on running CloudBees CI on Kubernetes, see the CloudBees CI 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.