A newer version of this documentation is available.

View Latest

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.