Cluster Deployment Tutorial

This tutorial walks you through the steps to deploy a three-node cluster with pre-loaded data.

This tutorial assumes the following:

You have a working knowledge of Kubernetes
You have deployed the Operator and it is up and running
You have reviewed the prerequisites and prepared your Kubernetes or OpenShift cluster to run Couchbase pods
You have administrative privileges for the Kubernetes or OpenShift cluster
You have downloaded the Operator package and installed cbopctl

cbopctl is a command line tool similar to kubectl or oc, except that it performs an extra check on the CouchbaseCluster configuration being sent to Kubernetes to ensure that it is valid.

The Operator package also contains YAML configuration files that you will use in this guide.

After you unpack the download, the resulting directory will be titled something like couchbase-autonomous-operator-kubernetes_x.x.x-linux_x86_64. Make sure to cd into this directory before you run the commands in this guide.

Ensure that your Kubernetes environment has the appropriate resources for the Couchbase cluster that you’re trying to deploy.

In the case of Minikube and Minishift, the default memory allocation is 2 GB. This is not sufficient for running a three-node Couchbase cluster like the one in the example configuration used in this guide. If you’re using the example configuration for demo purposes, you should set the memory allocation to 4 GB at a minimum (8 GB recommended). You should also increase the CPU allocation if you experience poor performance.

You can set the recommended memory and CPU allocation when you start Minikube or Minishift:

minikube start --cpus 2 --memory 8192

minishift start --cpus 2 --memory 8192

Create a Couchbase Cluster

Kubernetes
OpenShift

cbopctl apply -f  couchbase-cluster.yaml

cbopctl apply -f  couchbase-cluster.yaml

Create a Couchbase RBAC User

As part of this tutorial, you will be loading data into Couchbase, and therefore need to create a Couchbase RBAC user. RBAC users can be created by directly using the Couchbase CLI, or as a job within the Kubernetes cluster. (For more details, see the documentation about accessing the Couchbase Server user interfaces.

Option 1: Create a Default User With the Couchbase CLI

Get the Couchbase Server Web Console port:

Kubernetes
OpenShift

kubectl describe cbc cb-example |  grep "Admin Console Port:"

oc describe cbc cb-example |  grep "Admin Console Port:"

The result should be something like:

Admin Console Port: 32486

If you have Couchbase Server installed on your computer, use couchbase-cli to create a Couchbase RBAC user by running the following command:

./couchbase-cli user-manage -c <kubernetes-node-ip>:32486 -u Administrator -p password --rbac-username default --rbac-password password --roles admin --auth-domain local --set

You can now go to the next step: Loading data

Option 2: Create a Default User With a Kubernetes Job

Just as the admin user has a secret, the RBAC user also requires its own secret. Create a secret for the RBAC user, named default, by running the following commands:

$ echo -n "default" | base64
ZGVmYXVsdA==

$ echo -n "password" | base64
cGFzc3dvcmQ=

$ echo 'apiVersion: v1
kind: Secret
metadata:
  name: cb-user-auth
type: Opaque
data:
  default_user: ZGVmYXVsdA==
  default_password: cGFzc3dvcmQ=' >  cb-user-auth-secret.yaml

$ kubectl create -f  cb-user-auth-secret.yaml
secret "cb-user-auth" created

Now, use the RBAC user’s secret to securely create a Couchbase RBAC user using a Kubernetes or OpenShift job:

Kubernetes
OpenShift

$ kubectl create -f couchbase-cli-create-user.yaml
job "create-user" created

$ kubectl get job
NAME          DESIRED   SUCCESSFUL   AGE
create-user   1         1            4s

$ oc create -f couchbase-cli-create-user.yaml
job "create-user" created

$ oc get job
NAME          DESIRED   SUCCESSFUL   AGE
create-user   1         1            4s

If you’re not using the default namespace, edit the couchbase-cli-create-user.yaml file to reflect your namespace. For example, if your namespace is myproject, edit the command field in the YAML file to replace ${CLUSTER_NAME} with cb-example-0000.cb-example.myproject.svc. The updated field will now look like the following snippet:

command: ["/bin/sh", "-c", "/couchbase-cli-secure user-manage
                     -c cb-example-0000.cb-example.myproject.svc
                     -u {auth.admin.username}
                     -p {auth.admin.password}
                     --rbac-username {auth.users.default_user}
                     --rbac-password {auth.users.default_password}
                     --roles admin --auth-domain local --set"]

The name of the secret and its keys are very important as the sample create-user spec mounts the secrets into a volume.

couchbase-cli-create-user.yaml
---
apiVersion: batch/v1
kind: Job
metadata:
  name: create-user
spec:
...
      volumes:
        - name: cb-admin
          secret:
            secretName: cb-example-auth
        - name: cb-users
          secret:
            secretName: cb-user-auth

Loading data

Use the sample pillowfight job to load items into your cluster. The following spec loads 10k items into the Couchbase cluster:

apiVersion: batch/v1
kind: Job
metadata:
  name: pillowfight
spec:
  template:
    metadata:
      name: pillowfight
    spec:
      containers:
      - name: pillowfight
        image: couchbaseutils/pillowfight:v2.9.3
        command: ["cbc-pillowfight",
                  "-U", "couchbase://cb-example-0000.cb-example.default.svc/default?select_bucket=true",
                  "-I", "10000", "-B", "1000", "-c", "10", "-t", "1", "-P", "password"]
      restartPolicy: Never

If you’re not using the default namespace, you must update the pillowfight-data-loader.yaml file to reflect your namespace. For example, if your namespace is myproject, edit the command field in the YAML file to replace cb-example-0000.cb-example.default.svc with cb-example-0000.cb-example.myproject.svc. The updated field will now look like the following snippet:

command: ["cbc-pillowfight",

                  "-U", "couchbase://cb-example-0000.cb-example.myproject.svc/default?select_bucket=true",
                  "-I", "10000", "-B", "1000", "-c", "10", "-t", "1", "-P", "password"]

To deploy the pillowfight data loader, run the following command:

Kubernetes
OpenShift

kubectl create -f pillowfight-data-loader.yaml

oc create -f pillowfight-data-loader-openshift.yaml

Once it completes, you should have 10k items loaded into your cluster.