Table of contents

CloudBees Core on modern cloud platforms installation guide


Using Helm and CloudBees Core on OpenShift

The Helm package manager is the preferred method of installing CloudBees Core. It can be used to install CloudBees Core in two different ways:

  1. (Recommended) By using the Helm client with the Tiller server-side component. This automates much of the installation and provides the widest number of options.

  2. By using the Helm client with the Helm template command.

Why use Helm?

Using Helm to install CloudBees Core provides the following advantages:

  • It lets you customize CloudBees Core installation without resorting to error-prone modification of the CloudBees Core YAML files,

  • It provides a history of changes applied to CloudBees Core release,

  • It provides a simpler and more robust rollback option to you,

  • It provides a straightforward method of creating custom environment deployments of CloudBees Core.

For example: development, staging, and production CloudBees Core environments.

Things you should know before using Helm

As with any powerful tool, there can be disadvantages to using Helm.

  • It requires the installation of Tiller on the Kubernetes cluster to provide the most significant benefit.

  • It requires Cluster Admin rights, so that it can install Helm charts.

  • Helm prefers access to the Internet to download the Helm chart and the chart dependencies.

About Helm charts

A Helm chart is a package that defines a Kubernetes application and its dependencies.

The chart is a combination of YAML templates for Kubernetes resources, such as pods, replica sets, deployments or ingresses. It also provides a values file that populates default configuration values for the templates.

Instead of manually editing files, Helm manages the process by merging the templates files and the values into a custom YAML file. It then applies and tracks the deployment of the YAML file on the Kubernetes cluster.

Working with Helm in a secure environment

In a secure environment, you may not be able to use the Tiller server component or provide Tiller with the required permissions.

If you are in this situation, refer to the Securing your Helm Installation section of the Helm documentation.

If you aren’t able to use the methods in the Helm documentation, there is an alternate option that uses the helm template command to create a custom YAML file for your environment. However, this installation approach limits the features and functionality of the CloudBees Core Helm chart.

For instructions on installing CloudBees Core using helm template, see Using helm template to create custom YAML files.

Before you get started

Before using Helm, you need to set up three things that Helm will use:

OpenShift cluster

CloudBees Core runs on an OpenShift cluster, and to install a CloudBees Core cluster you will to meet these requirements:

  • A production release of OpenShift and OpenShift CLI and Helm: beta or test releases of OpenShift and Helm are not supported.

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

  • A project in the cluster (provided by your OpenShift admin) with permissions to create Role and RoleBinding policies.

  • Access to the DNS record that points to your installation

  • TLS certificates (needed when you deploy CloudBees Core)

  • A Default Storage Class defined and ready to use. Refer to the Storage Requirements section in the AWS or On-premise Reference Architectures for more information.

Setting up an OpenShift project

CloudBees recommends using an OpenShift project when you install CloudBees Core.

When combined with OpenShift RBAC security, a OpenShift administrator can use an OpenShift project to restrict who has access to a project and its data.

Important
Your Helm release name must be unique for the OpenShift cluster, not just your project.
  1. Create an OpenShift project, then set it as the current OpenShift project:

    $ oc new-project cjoc
    $ oc project tiller
Tip
The open-source tools kubectx and kubens make changing Kubernetes context or namespace easier. See the kubectx project for more details.

CloudBees Core administrative workstation

The CloudBees Core administrative workstation is the computer used to install, update and maintain CloudBees Core.

Tip

In organizations where multiple people are performing CloudBees Core administration duties, it may be beneficial to use a bastion host instead of setting up a workstation for each CloudBees Core administrator.

This workstation may be either the CloudBees Core administrative workstation or a Kubernetes administrative workstation: it just needs to be a workstation on which you have full command privileges for the following utilities:

Setting up the Helm client

To set up the Helm client, you need to install the Helm client and optionally install the Tiller server component. For additional information, see the OpenShift blog article Getting Started with Helm on OpenShift.

Note
Red Hat provides a custom OpenShift template as the recommended way to install Tiller on OpenShift, and these instructions use that method to install Tiller instead of the method described on the Helm website.
Installing the Helm client

Follow the instructions in the Helm project README to install the Helm client. Detailed instructions for specific operating systems are provided in the installation section.

Note
If you intend to use the Helm template option instead of Tiller, after installing the Helm client, you can skip to Using Helm template to create custom YAML files.
Installing Tiller

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

  1. Create and export the environment variables the Helm client needs:

    $ export TILLER_NAMESPACE=tiller
    $ export HELM_VERSION=v2.12
  2. Using the OpenShift CLI, create a new project in the OpenShift cluster:

    $ oc new-project tiller
    $ oc project tiller
  3. Using the OpenShift CLI, install the Tiller Server:

    $ oc process -f https://raw.githubusercontent.com/openshift/origin/master/examples/helm/tiller-template.yaml -p TILLER_NAMESPACE="${TILLER_NAMESPACE}" HELM_VERSION="${HELM_VERSION}" | oc create -f -
    $ oc rollout status deployment tiller
  4. Wait for the Tiller Server to start up:

    $ oc rollout status deployment tiller
  5. Once the Tiller server deployment completes, you will see the following message:

    Waiting for rollout to finish: 0 of 1 updated replicas are available...
    deployment "tiller" successfully rolled out
  6. Using the OpenShift CLI, grant Tiller permissions to access the OpenShift project:

    $ oc policy add-role-to-user admin "system:serviceaccount:${TILLER_NAMESPACE}:tiller"
  7. Verify that Helm and Tiller are working:

    $ ./helm version
    Client: &version.Version{SemVer:"v2.9.0", GitCommit:"f6025bb9ee7daf9fee0026541c90a6f557a3e0bc", GitTreeState:"clean"}
    Server: &version.Version{SemVer:"v2.9.0", GitCommit:"f6025bb9ee7daf9fee0026541c90a6f557a3e0bc", GitTreeState:"clean"}

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

Helm uses CloudBees' public chart repository to automatically download the CloudBees Core Helm chart. If you are unable or do not wish to use the CloudBees Core Helm Chart Repository, the you can download the CloudBees Core Helm Chart from same download site as the CloudBees Core installation package.

Adding the CloudBees Helm Chart Repository

Before you can use the CloudBees repository you must add it to your Helm environment with the helm repo add command.

To add the CloudBees Public Helm Chart Repository to your Helm environment:

$ helm repo add cloudbees https://charts.cloudbees.com/public/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.

Tip
Always run helm repo update before you execute a helm search using helm search. This ensures your cache is upto date.

Downloading the Helm Chart

The CloudBees Core download site also includes the CloudBees Core Helm chart archive.

To download the latest helm-chart Helm archive package from https://downloads.cloudbees.com/cloudbees-core/cloud/latest:

$ export INSTALLER=cloudbees-core-helm-chart.tgz
$ sha256sum -c cloudbees-core-helm-chart.tgz.sha256