A newer version of this documentation is available.

View Latest

Installing on Kubernetes


    This guide walks through the recommended procedure for installing the Couchbase Autonomous Operator on an open source Kubernetes cluster that has RBAC enabled.

    This guide assumes the following:
    • You have a working knowledge of Kubernetes

    • You have reviewed the prerequisites

    • You are installing on a new Kubernetes cluster that has RBAC enabled

    • You have administrative privileges for the Kubernetes cluster

    If you have a Kubernetes environment that already has a custom setup (non-default), you should be able to modify a few of the parameters in the various commands and configuration files mentioned in this guide to fit your requirements.

    This guide makes certain assumptions about the role-based access control (RBAC) settings in your Kubernetes environment. Refer to the RBAC doumentation before you install the Operator, as your Kubernetes environment may differ from the environment upon which this guide is based.


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

    The Operator package contains YAML configuration files and command-line tools that you will use to install the Operator.

    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.

    Create a Cluster Role

    The first step to installing the Operator is to create a cluster role that allows the Operator to access the resources that it needs to run. Since the Operator might run in many different namespaces, it is best to create a cluster role because you can assign that role to a service account in any namespace.

    To create the cluster role for the Operator, run the following command:

    kubectl create -f cluster-role.yaml
    This cluster role only needs to be created once.

    Create a Service Account

    After the cluster role is created, you need to create a service account in the namespace where you are installing the Operator, and then assign the cluster role to that service account using a cluster role binding. (In this example, the service account is created in the namespace called default.)

    To create the service account:

    kubectl create serviceaccount couchbase-operator --namespace default

    To assign the cluster role to the service account:

    kubectl create clusterrolebinding couchbase-operator --clusterrole couchbase-operator --serviceaccount default:couchbase-operator
    If you would prefer to use a role binding instead of a cluster role binding, then the CRD needs to be installed separately from the Operator. This can be accomplished by removing the -create-crd argument from the operator.yaml file and uploading the CRD separately.

    Create the Operator

    Now that the service account is set up with the appropriate permissions, you can create and start the Operator by running the following command:

    kubectl create -f operator.yaml

    Running this command downloads the Operator Docker image (specified in the operator.yaml file) and creates a deployment, which manages a single instance of the Operator. The Operator uses a deployment so that it can restart if the pod it’s running in dies.

    After you run the kubectl create command, it generally takes less than a minute for Kubernetes to deploy the Operator and for the Operator to be ready to run.

    Check the Status of the Deployment

    You can use the following command to check on the status of the deployment:

    kubectl get deployments -l app=couchbase-operator

    If you run the this command immediately after the Operator is deployed, the output will look something like the following:

    couchbase-operator   1         1         1            0           10s

    In this case, the deployment is called couchbase-operator. The DESIRED field in the output shows that this deployment will create one pod running the Operator. The CURRENT field shows that one Operator pod has been created. However, the AVAILABLE field indicates that the pod is not ready yet since its value is 0 and not 1. That means that the Operator is still establishing a connection to the Kubernetes master node to allow it to get updates on CouchbaseCluster objects. Once the Operator has completed this task, it will be able to start managing Couchbase Server clusters and the status will be shown as AVAILABLE.

    You should continue to poll the status of the Operator until the output looks similar to the following:

    couchbase-operator   1         1         1            1           47s

    Check the Status of the Operator

    You can use the following command to verify that the Operator has started successfully:

    kubectl get pods -l app=couchbase-operator

    If the Operator is up and running, the command returns an output where the READY field shows 1/1, such as:

    NAME                                  READY   STATUS   RESTARTS   AGE
    couchbase-operator-1917615544-t5mhp   1/1     Running  0          57s

    You can also check the logs to confirm that the Operator is up and running. Look for the message: CRD initialized, listening for events…​ module=controller.

    kubectl logs couchbase-operator-1917615544-t5mhp

    You should see output similar to the following:

    time="2018-04-25T03:01:56Z" level=info msg="Obtaining resource lock" module=main
    time="2018-04-25T03:01:56Z" level=info msg="Starting event recorder" module=main
    time="2018-04-25T03:01:56Z" level=info msg="Attempting to be elected the couchbase-operator leader" module=main
    time="2018-04-25T03:02:13Z" level=info msg="I'm the leader, attempt to start the operator" module=main
    time="2018-04-25T03:02:13Z" level=info msg="Creating the couchbase-operator controller" module=main
    time="2018-04-25T03:02:13Z" level=info msg="Event(v1.ObjectReference{Kind:\"Endpoints\", Namespace:\"default\", Name:\"couchbase-operator\", UID:\"9b86c750-47e7-11e8-866e-080027b2a68d\", APIVersion:\"v1\", ResourceVersion:\"23482\", FieldPath:\"\"}): type: 'Normal' reason: 'LeaderElection' couchbase-operator-75ddfdbdb5-bz7ng became leader" module=event_recorder
    time="2018-04-25T03:02:13Z" level=info msg="CRD initialized, listening for events..." module=controller
    time="2018-04-25T03:02:13Z" level=info msg="starting couchbaseclusters controller"

    Next Steps

    Install the cbopctl command line tool and use it to deploy a Couchbase Server cluster.

    Uninstalling the Operator

    Uninstalling the Operator is a two-step process:
    1. Delete the Operator.

      kubectl delete deployment couchbase-operator
    2. Delete the CRD.

      Make sure all instances of the Operator have been deleted from the Kubernetes cluster before you delete the CRD. Once all instances of the Operator have been deleted, run the following command to delete the CRD:

      kubectl delete crd couchbaseclusters.couchbase.com