Helm Setup Guide

Helm is a tool that streamlines the installation and management of applications on Kubernetes platforms. Official Couchbase Helm charts can help you easily set up the Couchbase Autonomous Operator.

This page describes how to set up Helm to properly support the Couchbase Autonomous Operator in your Kubernetes or OpenShift environment. Setting up Helm consists of installing the Helm client (helm) on your computer, and installing the Helm server (Tiller) on your Kubernetes or OpenShift cluster. Once you’ve set up Helm, you can then use official Couchbase Helm charts to deploy the Operator and the Couchbase Server cluster.

Installing Helm

Install the Helm Client

Follow Helm’s official steps for installing helm on your operating system.

It’s helpful to install helm on the same computer where you normally run kubectl or oc.

Install the Helm Server (Tiller)

After you’ve installed helm, you’ll need to install Tiller — the server portion of Helm that runs inside of your Kubernetes cluster.

Follow Helm’s official steps for installing Tiller on your Kubernetes cluster.

Installing Tiller for Development

For development use-cases, the Tiller service can be given access to deploy charts into any namespace of your Kubernetes cluster. This also means that resources created by the chart, such as the custom resource definition (CRD), are allowed when Tiller is given this level of privilege.

To create RBAC rules for Tiller with cluster-wide access create the following ServiceAccount and save to rbac-tiller.yaml

apiVersion: v1
kind: ServiceAccount
metadata:
  name: tiller
  namespace: kube-system
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: tiller
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
  - kind: ServiceAccount
    name: tiller
    namespace: kube-system

Now install the ServiceAccount and initialize Helm

kubectl create -f rbac-tiller.yaml
helm init --service-account tiller

Installing Tiller for Production

For production use-cases, it’s recommended that you restrict the Tiller service to deploying charts only into namespaces that will be used by Helm. This ensures that your applications are operating in the scope that you’ve specified.

To create RBAC rules for Tiller that have restricted access, refer to the Helm documentation about deploying Tiller in a namespace such that it’s restricted to deploying resources only in that namespace.

When Tiller is restricted to a single namespace, the Operator won’t be able to automatically install the custom resource definition (CRD) that’s required to create Couchbase clusters. See the production deployment instructions for information about manually installing the CRD.

Deploying the Operator and Couchbase Server

Two Helm charts are available for deploying Couchbase. The Couchbase Operator Chart deploys the admission controller and the Operator itself. The Couchbase Cluster Chart deploys the Couchbase Server cluster.

For production deployments, you’ll only use the Operator Chart. For development environments, the Couchbase Cluster Chart is available to help you quickly set up a test cluster.

Deploying for Development (Quick Start)

To quickly deploy the admission controller and Operator, as well as a Couchbase Server cluster for development purposes:

  • Kubernetes

  • OpenShift

  1. Add the chart repository to helm:

    helm repo add couchbase https://couchbase-partners.github.io/helm-charts/
  2. Install the Operator Chart:

    helm install couchbase/couchbase-operator
  3. Install the Couchbase Cluster Chart:

    helm install couchbase/couchbase-cluster
  1. Add the chart repository to helm:

    helm repo add couchbase https://couchbase-partners.github.io/helm-charts/
  2. Create an imagePullSecret for retrieving images from the Red Hat Container Catalog:

    oc create secret docker-registry rh-catalog \
      --docker-server=registry.connect.redhat.com \
      --docker-username=<rhel-username> \
      --docker-password=<rhel-password> \
      --docker-email=<docker-email>
  3. Create a file named openshift_values.yaml with the following custom override values for the Oprator Chart:

    couchbaseOperator:
      image:
        repository: registry.connect.redhat.com/couchbase/operator
        tag: 1.2.2
      imagePullSecrets:
      - rh-catalog
    admissionController:
      image:
        repository: registry.connect.redhat.com/couchbase/admission-controller
        tag: 1.2.2
      imagePullSecrets:
      - rh-catalog
  4. Install the Operator Chart with the custom override values:

    helm install -f openshift_values.yaml couchbase/couchbase-operator
  5. Install the Couchbase Cluster Chart with the desired Couchbase images from the Red Hat Container Catalog:

    helm install \
      --set couchbaseCluster.baseImage=registry.connect.redhat.com/couchbase/server \
      --set  couchbaseCluster.version=6.0.1-1 \
      couchbase/couchbase-cluster

Deploying for Production

For production deployments, additional customization is required in order to restrict the RBAC roles of the Operator to a single namespace. Note that this restriction requires that the CRD be manually created. This is because the CRD is a cluster-wide resource and cannot be created by the Operator when it has restricted access.

The following steps show the minimum requirements for deploying the Operator Chart under the above constraints for production usage:

  1. Download the appropriate Operator package and unpack it on the same computer where you normally run kubectl or oc.

  2. Included in the package is a file called crd.yaml. Use the following command to install it on your Kubernetes cluster:

    • Kubernetes

    • OpenShift

    kubectl create -f crd.yaml
    oc create -f crd.yaml

    Ensure that you’re logged in as an OpenShift user that has cluster-admin privileges when you run this command.

  3. Add the chart repository to helm:

    helm repo add couchbase https://couchbase-partners.github.io/helm-charts/
  4. Install the Operator Chart:

    helm install --set rbac.clusterRoleAccess=false couchbase/couchbase-operator

    The above command uses the --set option to override the chart’s default rbac.clusterRoleAccess parameter and sets it to false. This is the most important parameter to modify for production environments. However, you may need to override additional parameters to meet the needs of your environment. Therefore, it’s recommended that you keep all of your overrides in a YAML file, and use the the --values option instead of the --set option when you install the chart. See Customizing Helm Charts for more information.

    When you install a chart, Helm autogenerates a name for the release (usually a unique set of dictionary words). Helm prepends this name to all of the objects and resources that the chart creates.

    If you plan to use Helm to install multiple instances of the Operator, you should consider giving each release a unique name to help you more easily identify the resources that are associated with each release. You can specify a name for the release during chart installation by using the --name flag:

    helm install -n <unique-name> --set rbac.clusterRoleAccess=false couchbase/couchbase-operator
  5. Deploy the Couchbase Server cluster using the traditional method of using a CouchbaseCluster specification.

    Note that you’re not deploying the Couchbase cluster using a Helm chart. Due to the complex structure of production configurations (which usually include server groups and persistent volumes), Couchbase clusters are better expressed and managed directly using a cluster spec.

Customizing Helm Charts

The official Couchbase Helm charts are great to use "as-is" for quickly deploying Couchbase on Kubernetes platforms, but you’ll undoubtedly need to customize them for your specific development and production needs. All of the values that are exposed by the charts are available within the values.yaml file of the Couchbase Operator Chart and the Couchbase Cluster Chart.

You can customize each chart by using overrides. There are two methods to specify overrides during chart installation: --values and --set.

  • --values

  • --set

The --values option is the preferred method because it allows you to keep your overrides in a YAML file, rather than specifying them all on the command line.

  1. Create a YAML file and add your overrides to it.

    Here’s an example called myvalues.yaml:

    couchbaseOperator:
      imagePullPolicy: Always
  2. Specify your overrides file when you install the chart:

    helm install --values myvalues.yaml couchbase/coucbase-operator

    The values in your overrides file (myvalues.yaml) will override their counterparts in the chart’s values.yaml file. Any values in values.yaml that weren’t overridden will keep their defaults.

If you only need to make minor customizations, you can specify them on the command line by using the --set option.

Here’s an example:

helm install --set rbac.clusterRoleAccess=false couchbase/couchbase-operator

This would translate to the following in the values.yaml of the chart:

rbac:
  clusterRoleAccess: true

For more information about each chart, see the following:

Operator Chart
Couchbase Cluster Chart

Chart Versions

The helm install command will always pull the highest version of a chart. To list the versions of the chart that are available for installation, you can run the helm search command:

helm search --versions couchbase/couchbase-operator
NAME                        	CHART VERSION	APP VERSION	DESCRIPTION
couchbase/couchbase-operator	0.1.2        	1.2        	A Helm chart for Kubernetes

Here, the CHART VERSION is 0.1.2, and the APP VERSION (the Couchbase Operator version) is 1.2.

To install a specific version of a chart, include the --version argument during installation:

helm install --version 0.1.2 couchbase/couchbase-operator

If you’re having trouble finding or installing a specific version of a chart, use the helm repo update command to ensure that you have the latest list of charts.