Get Started with Couchbase Service Broker on Kubernetes

    +
    This page describes how to get and install the Couchbase Service Broker and create your first service instance.

    The Couchbase Service Broker is just a simple web-service that creates Kubernetes resources on demand as requested by the API. This guide will walk you through the steps to install and get started with Couchbase Service Broker on Kubernetes.

    Prerequisites

    This section describes the platform and software requirements for running the Service Broker.

    Kubernetes Cluster

    The following platforms are supported:

    • Kubernetes 1.17+

      • Includes managed Kubernetes platforms AWS EKS, Azure AKS, and Google GKE

    In general, any Kubernetes distribution based on a supported version should work.

    Red Hat OpenShift is not supported, as Template Service Broker and Service Catalog have been deprecated and removed from the latest OpenShift releases.

    Kubernetes Service Catalog

    The Couchbase Service Broker is intended to be used in Kubernetes-based environments, therefore the Kubernetes Service Catalog is required to be installed on your Kubernetes cluster. Since the Service Broker is standards based, any version of the Kubernetes Service Catalog that is compatible with Open Service Broker API 2.13+ is supported.

    Installation instructions can be found in the official Kubernetes documentation, including a guide on how to install the Service Catalog using Helm.

    Package Downloads

    Before you can proceed with rest of the steps in this guide, you’ll need to download the necessary packages from https://www.couchbase.com/downloads.

    Please download the following packages:

    • Couchbase Service Broker 1.1

    • Couchbase Autonomous Operator 2.1 or 2.2

    Both of these packages contain YAML configuration files and command-line tools that you will use to install the Couchbase Service Broker and Couchbase Clusters.

    Make sure to unpack these packages on the same computer where you normally run kubectl. The resulting directory will be titled something like couchbase-service-broker-kubernetes. Make sure to cd into this directory before you run the remaining commands in this guide.

    Install the Required Command-line Tools

    Install cbcsctl

    The Couchbase Service Broker package includes a command-line tool named cbsbctl, which is used during installation. Use the steps below to install cbsbctl on your platform of choice.

    • macOS

    • Linux

    • Windows

    1. Open a Terminal window and go to the directory where the cbsbctl binary is located:

      $ cd couchbase-service-broker-kubernetes/
    2. Make the cbsbctl binary executable:

      $ chmod +x ./cbsbctl.darwin
    3. Move the binary into your PATH:

      $ sudo mv ./cbsbctl /usr/local/bin/cbsbctl
    1. Open a command prompt and go to the directory where the cbsbctl binary is located:

      $ cd couchbase-service-broker-kubernetes/
    2. Make the cbsbctl binary executable:

      $ chmod +x ./cbsbctl
    3. Move the binary into your PATH:

      $ sudo mv ./cbsbctl /usr/local/bin/cbsbctl
    1. Open a command prompt and go to the directory where the cbsbctl binary is located:

      $ cd couchbase-service-broker-kubernetes\
    2. Add the cbsbctl.exe binary into your PATH.

    Install cbopcfg

    The Couchbase Autonomous Operator package includes a command-line tool named cbsbctl, which is used to install certain dependencies for the Autonomous Operator. Use the steps below to install cbopcfg on your platform of choice.

    • macOS

    • Linux

    • Windows

    1. Open a Terminal window and go to the directory where the cbopcfg binary is located:

      $ cd couchbase-autonomous-operator-kubernetes_x.x.x-macos_x86_64/bin/
    2. Make the cbopcfg binary executable:

      $ chmod +x ./cbopcfg
    3. Move the binary into your PATH:

      $ sudo mv ./cbopcfg /usr/local/bin/cbopcfg
    1. Open a command prompt and go to the directory where the cbopcfg binary is located:

      $ cd couchbase-autonomous-operator-kubernetes_x.x.x-linux_x86_64/bin/
    2. Make the cbopcfg binary executable:

      $ chmod +x ./cbopcfg
    3. Move the binary into your PATH:

      $ sudo mv ./cbopcfg /usr/local/bin/cbopcfg
    1. Open a command prompt and go to the directory where the cbopcfg binary is located:

      $ cd couchbase-autonomous-operator-kubernetes_x.x.x-windows_x86_64\bin\
    2. Add the cbopcfg binary into your PATH.

    Install the Required Dependencies

    All of the Kubernetes command-line examples in this guide assume the default namepsace, unless stated otherwise.

    Install the Service Broker CRD

    The Service Broker is configured using a Kubernetes custom resource that allows type checking of your configurations. In order to use this custom resource, you must install the custom resource definition (CRD) that is included in the Service Broker package download.

    From the unpacked Service Broker directory:

    $ kubectl create -f crd.yaml

    Install the Autonomous Operator CRDs and Dynamic Admission Controller

    The included service plans deploy instances of the Autonomous Operator, which has its own dependencies.

    From the unpacked Autonomous Operator directory, run the following command to install the Autonomous Operator CRD:

    $ kubectl create -f crd.yaml

    Next, run the following command to install the dynamic admission controller (DAC) into the default namespace.

    $ bin/cbopcfg create admission

    If running Autonomous Operator 2.1, use the following command instead:

    $ bin/cbopcfg generate admission | kubectl create -f -

    The above commands were taken from the Autonomous Operator installation guide. Please refer to that guide for additional information about installing these dependencies, including steps to verify proper installation.

    Install the Service Broker

    The following commands can be used to install the Service Broker configuration and service. The Service Broker can be installed at the namespace level or the cluster level.

    • namespace

    • cluster

    $ ./cbsbctl create servicebroker --profile demo
    $ ./cbsbctl create clusterservicebroker --profile demo

    The ServiceAccount that the Service Broker runs as is bound to a ClusterRole. A Secret contains the TLS configuration and bearer token for authentication as the Service Broker is secure by default.

    If you wish to deploy the Service Broker in a namespace other than default, you will need to manually generate TLS certificates. Your CA certificate must be installed in the couchbase-service-broker cluster service broker, defined in clusterservicebroker.yaml. Your server certificate or certificate chain, and private key, must be installed in the couchbase-service-broker secret, defined in broker.yaml. The server certificate must have a subject alternative name (SAN) valid for the service broker service.

    For example, if the service broker service is called couchbase-service-broker and it will be installed in the foo namespace, then your server certificate should have a DNS SAN valid for couchbase-service-broker.foo.svc.

    Finally, you must update any resources references to the default namespace, to foo. These can be found in the couchbase-service-broker cluster role binding defined in broker.yaml and the couchbase-service-broker cluster service broker defined in clusterservicebroker.yaml.

    The Deployment creates the Service Broker and ensures it is highly available and a Service makes it discoverable by the Kubernetes Service Catalog in the next step.

    You can run the following command to check the status of the Service Broker:

    $ kubectl get deployments
    NAME                          	 	READY   	UP-TO-DATE   AVAILABLE   	AGE
    couchbase-operator-admission   		 1/1     		1             1        	37m
    couchbase-service-broker       		 1/1     		1            	1         32m

    Provision the Couchbase Cluster Service

    The following service classes are available to choose from:

    • Class: cao-2.1-service

      • Plan: csb-basic

      • Plan: csb-standard

    • Class: cao-2.2-service

      • Plan: csb-basic

      • Plan: csb-standard

    The following command deploys a three-node cluster (by default), with a Bucket, and an Administrator user with a password.

    $ svcat provision csb --class cao-2.2-service --plan csb-basic --param password=password --wait

    Bind to the Provisioned Service

    $ svcat bind csb
    Name:        csb
        Namespace:   default
        Status:
        Secret:      csb
        Instance:    csb
    
      Parameters:
        No parameters defined

    This will create a user and allow access to the bucket. Connection string, username, password, and CA certificate will be in the secret, ready to be used by a client of some variety.

    $ kubectl get secrets csb
    NAME   TYPE     DATA   AGE
    csb    	Opaque       5      7m58s

    To access the Couchbase Web Console:

    $ kubectl port-forward couchbase-instance-winhhoku-0000 8091

    Go to http://localhost:8091 and login with the credentials used when provisioning the Couchbase cluster service.