CouchbaseCluster Configuration

CouchbaseCluster Configuration

CouchbaseCluster Configuration

The following sample CouchbaseCluster configuration file lists all of the configuration parameters:

apiVersion: couchbase.database.couchbase.com/v1beta1
kind: CouchbaseCluster
metadata:
  name: cb-example
  namespace: default
spec:
  baseImage: couchbase/server
  version: enterprise-5.0.1
  paused: false
  antiAffinity: true
  authSecret: my-secret
  exposeAdminConsole: true
  adminConsoleServices:
    - data
  cluster:
    dataServiceMemoryQuota: 256
    indexServiceMemoryQuota: 256
    searchServiceMemoryQuota: 256
    indexStorageSetting: default
    autoFailoverTimeout: 30
  buckets:
    - name: default
      type: couchbase
      memoryQuota: 1024
      replicas: 1
      ioPriority: high
      eviction-policy: value-eviction
      conflictResolution: seqno
      enableFlush: true
      enableIndexReplica: false
  servers:
    - size: 1
      name: all_services
      services:
        - data
        - index
        - query
        - search
      dataPath: /opt/couchbase/var/lib/couchbase/data
      indexPath: /opt/couchbase/var/lib/couchbase/data
      pod:
        couchabseEnv:
          ENV1: value
        resources:
          limits:
            cpu: 4GHz
            memory: 8GiB
            storage: 100GiB
          requests:
            cpu: 2GHz
            memory: 8GiB
            storage: 50GiB
        labels:
          couchbase_services: all
        nodeSelector:
          instanceType: large
        tolerations:
          - key: app
            operator: Equal
            value: cbapp
            effect: NoSchedule
        automountServiceAccountToken: false

Top-Level Definitions

The following are the top-level parameters for a CouchbaseCluster configuration:

apiVersion: couchbase.database.couchbase.com/v1beta1
kind: CouchbaseCluster
metadata:
  name: cb-example
  namespace: default
spec:
...

apiversion

This field specifies the API Version for our integration. As our integration changes over time, you can change the API Version whenever new features are added. For any given release, the API Versions that are supported by that Operator will be specified in our documentation. We also always recommend that you upgrade to the latest API Version when possible.

Field rules: This field is required and must be set to a valid API Version. The value of this field cannot be changed after the cluster is created.

kind

This field specifies that this Kubernetes configuration will use the custom Couchbase controller to manage the cluster.

Field rules: This field is required and must always be set to CouchbaseCluster. The value of this field cannot be changed after the cluster is created.

metadata

Allows setting a name for the Couchbase cluster and a namespace that the cluster should be deployed in.

Field rules: A name is highly recommended, but not required. If values are not set in the metadata field then defaults will be set. The value of name will be autogenerated and the value of namespace will be set to default. The value of these fields cannot be changed after the cluster is created.

spec

This field contains the specification on how the Couchbase cluster must be deployed.

Spec: The Top-Level

This section describes the top-level parameters related to a Couchbase cluster deployment.

...
  baseImage: couchbase/server
  version: enterprise-5.0.1
  paused: false
  antiAffinity: true
  authSecret: my-auth-secret
  exposeAdminConsole: true
  adminConsoleServices:
    - data
...

baseImage

This field specifies the image that should be used.

Field rules: The baseImage field is required and should be set to couchbase/server unless you want Kubernetes to pull the Couchbase Server docker container from a different location. The value of this field cannot be changed after the cluster is created.

version

This field specifies the version number of Couchbase Server to install. This should match an available version number in the Couchbase Docker repository. It may never be changed to a lower version number than the version that is currently running.

Field rules: The version field is required and should be set to the version of Couchbase Server that should be used to build the cluster. At the time of this writing, the Couchbase Operator has only been tested with enterprise-5.0.1. The value of this field cannot be changed after the cluster is created.

paused

This field specifies whether or not the Operator is currently managing this cluster. This parameter should generally be set to true, but may be set to false if you decide to make manual changes to the cluster. By disabling the Operator you can change the cluster configuration without having to worry about the Operator reverting the changes. However, before re-enabling the Operator, ensure that the Kubernetes configuration matches the cluster configuration.

Field rules: The paused field is not required and defaults to false if not specified.

antiAffinity

This field specifies whether or not two pods in this cluster can be deployed on the same Kubernetes node. In a production setting this parameter should always be set to true in order to reduce the chance of data loss in case a Kubernetes node crashes.

Field rules: The antiAffinity field is not required and defaults to false if not specified. The value of this field cannot be changed after the cluster is created.

authSecret

This field specifies the name of a Kubernetes Secret that should be used as the user name and password of the Couchbase super-user.

Field rules: The authSecret field is required and should reference the name of a Kubernetes Secret that already exists. The value of this field cannot be changed after the cluster is created.

exposeAdminConsole

This field specifies whether or not the Couchbase Server Web Console should be exposed externally. Exposing the web console is done using a NodePort service and the port for the service can be found in the describe output when describing this cluster. This parameter may be changed while the cluster is running and the Operator will create/destroy the NodePort service as appropriate.

Field rules: The exposeAdminConsole field is not required and defaults to false if not specified.

adminConsoleServices

When the Couchbase Server Web Console is exposed, the pod that it is connected to is chosen based on the client IP address. Since the web console may display slightly different features based on the services running on the particular pod it is connected to, we let you specify the services so that the exposed port will only connect to pods that contain the services specified for this parameter. A list of one or more services should be provided. If you do not specify any service, then the web console will be connected to all pods in the cluster.

Field rules: The adminConsoleServices list is not required and defaults to an empty list. An empty list means any node in the cluster may be chosen when connecting to the Couchbase Server Web Console.

Spec: The Cluster Settings

This section describes the various Couchbase cluster settings. This section is not meant to encompass every setting that is configurable on Couchbase. Cluster settings not mentioned here can be managed manually.

...
  cluster:
    dataServiceMemoryQuota: 4096
    indexServiceMemoryQuota: 1024
    searchServiceMemoryQuota: 2048
    indexStorageType: plasma
    autoFailoverTimeout: 30
...

dataServiceMemoryQuota

The amount of memory to assign to the data service if it is present on a specific Couchbase node. The amount of memory is defined in Megabytes (MB).

Field rules: The dataServiceMemoryQuota field is required and must be set to be greater than or equal to 256. Keep in mind that the sum of all memory quotas must be no more than 80% of a pod’s available memory.

indexServiceMemoryQuota

The amount of memory to assign to the index service if it is present on a specific Couchbase node. The amount of memory is defined in Megabytes (MB).

Field rules: The indexServiceMemoryQuota field is required and must be set to be greater than or equal to 256. Keep in mind that the sum of all memory quotas must be no more than 80% of a pod’s available memory.

searchServiceMemoryQuota

The amount of memory to assign to the search service if it is present on a specific Couchbase node. The amount of memory is defined in Megabytes (MB). This parameter defaults to 256 MB if it is not set.

Field rules: The searchServiceMemoryQuota field is required and must be set to be greater than or equal to 256. Keep in mind that the sum of all memory quotas must be no more than 80% of a pod’s available memory.

indexStorageType

Specifies the backend storage type to use for the index service. If the cluster already contains a Couchbase Server instance running the index service, then this parameter cannot be changed until all Couchbase instances running the index service are removed.

Field rules: The indexStorageType is required and must be set to either plasma or memory-optimized. The value of this field can only be changed if there are no index nodes in the cluster.

autoFailoverTimeout

Specifies the auto-failover timeout in seconds. The Operator relies on the CouchbaseCluster to auto-failover nodes before removing them, so setting this field to an appropriate value is important.

Field rules: The autoFailoverTimeout is required and must be greater than or equal to 5.

Spec: Bucket Settings

This section describes one or more buckets that must be created in the cluster.

Note: If you remove an already specified bucket from the configuration, the Operator will delete that bucket from the cluster.

...
  buckets:
    - name: default
      type: couchbase
      memoryQuota: 1024
      replicas: 1
      ioPriority: high
      evictionPolicy: value-eviction
      conflictResolution: seqno
      enableFlush: true
      enableIndexReplica: false
...

name

This field specifies the name of the bucket. This parameter is required when specifying a bucket.

Field rules: The name is required and must be a string using characters and numbers. The value of this field cannot be changed after the bucket is created.

type

This field specifies the type of bucket to create. This parameter can be set to couchbase, ephemeral, or memcached. If the type is not specified, it defaults to couchbase.

Field rules: The type is required and must be set to either couchbase, ephemeral, or memcached. The value of this field cannot be changed after the bucket is created.

memoryQuota

This field specifies the amount of memory to allocate to this bucket in Megabytes (MB). If the quota is not specified, it defaults to 100.

Field rules: The memoryQuota is required and must be set to greater than or equal to 100.

replicas

This field specifies the number of replicas that should be created for this bucket. This value may be set between 0 and 3 inclusive. If the number is not set, it defaults to 1. Note that this parameter has no effect for the memcached bucket type.

Field rules: The replicas field is required for buckets with type couchbase and ephemeral and must be set between 0 and 3. Memcached buckets will ignore values in this field. Changing the value of this field will cause a rebalance to occur.

ioPriority

This field sets the IO priority of background threads for this bucket. This option is valid for Couchbase and Ephemeral buckets only. Memcached buckets will ignore values in this field.

Field rules: The ioPriority is required for buckets with type couchbase and ephemeral and must be set to either high or low. Memcached buckets will ignore values in this field. Changing the value of this field will cause downtime while the bucket is restarted.

evictionPolicy

This field sets the memory-cache eviction policy for this bucket. This option is valid for Couchbase and Ephemeral buckets only.

Couchbase buckets support either valueOnly or fullEviction. Specifying the valueOnly policy means that each key stored in this bucket must be kept in memory. This is the default policy; using this policy improves the performance of key-value operations, but limits the maximum size of the bucket. Specifying the fullEviction policy means that the performance is impacted for key-value operations, but the maximum size of the bucket is unbounded.

Ephemeral buckets support either noEviction or nruEviction. Specifying noEviction means that the bucket will not evict items from the cache if the cache is full. This type of eviction policy should be used for in-memory database use cases.

Specifying nruEviction means that items not recently used will be evicted from memory when all the memory in the bucket is used. This type of eviction policy should be used for caching use cases.

Field rules: The evictionPolicy is required for buckets with type couchbase and ephemeral. Memcached buckets will ignore values in this field. Changing the value of this field will cause downtime while the bucket is restarted.

conflictResolution

This field specifies the bucket’s conflict resolution mechanism which is to be used if a conflict occurs during cross-datacenter replication (XDCR). There are two supported mechanisms: sequence-based and timestamp-based.

The sequence-based conflict resolution mechanism selects the document that has been updated the greatest number of times since the last sync. For example, if one cluster has updated a document twice since the last sync, and the other cluster has updated the document three times, the document updated three times is selected regardless of the specific times at which these updates took place.

The timestamp-based conflict resolution mechanism selects the document with the most recent timestamp. This is only supported when all of the clocks on all of the nodes are fully synchronized.

Field rules: The conflictResolution field is required for buckets with type couchbase and ephemeral and can be set to either seqno or lww. Memcached buckets will ignore values in this field. The value of this field cannot be changed after the bucket has been created.

enableFlush

This field specifies whether or not to enable the flush command on this bucket. This parameter defaults to false if it is not specified. This parameter only affects Couchbase and Ephemeral buckets.

Field rules: The enableFlush field can be set to either true or false. If this parameter is not specified, it defaults to false.

enableIndexReplicas

This field specifies whether or not to enable view index replicas for this bucket. This parameter defaults to false if it is not specified. This parameter only affects Couchbase buckets.

Field rules: The enableIndexReplicas field is required for buckets with type couchbase and can be set to either true or false. Memcached and Ephemeral buckets will ignore values in this field.

Spec: Servers

You must specify at least one - but possibly multiple - node specifications. A node specification is used to allow multi-dimensional scaling of a Couchbase cluster with Kubernetes.

...
  servers:
  - size: 1
    name: all_services
    services:
      - data
      - index
      - query
      - search
    dataPath: /opt/couchbase/var/lib/couchbase/data
    indexPath: /opt/couchbase/var/lib/couchbase/data
    pod:
      couchabseEnv:
        CB_ENV_VAR: value
      resources:
        limits:
          cpu: 4GHz
          memory: 8GiB
          storage: 100GiB
        requests:
          cpu: 2GHz
          memory: 8GiB
          storage: 50GiB
      labels:
        couchbase_services: all
      nodeSelector:
        instanceType: large
      tolerations:
        - key: app
          operator: Equal
          value: cbapp
          effect: NoSchedule

Specification rules: The servers portion of the specification is required and must always contain at least one server definition. There must also be at least one definition that contains the data service.

size

This field specifies the number of nodes of this type that should be in the cluster. This allows the user to scale up different parts of the cluster as necessary. If this parameter is changed at runtime, the Operator will automatically scale the cluster.

Field rules: The size is required and can be set to greater than or equal to 1.

name

This field specifies a name for this group of servers.

Field rules: The name field is required and must be unique in comparison to the name field of other server definitions. The value of this field cannot be changed after a server has been defined.

services

This field specifies a list of services that should be run on nodes of this type. Users can specify data, index, query, and search in the list. At least one service must be specified and all clusters must contain at least one node specification that includes the data service.

Field rules: The services list is required and must contain at least one service. Valid values for services are data, index, query, and search. The values of this list cannot be changed after a server has been defined.

dataPath

This field specifies the path where data from the data service should be stored. This parameter is required.

Field rules: The dataPath is required and be set to a valid path. The value of this field cannot be changed after a server has been defined.

indexPath

This field specifies the path were data created by indexes should be stored. This parameter is required.

Field rules: The indexPath is required and be set to a valid path. The value of this field cannot be changed after a server has been defined.

The Pod Policy

The pod policy defines settings that apply to all pods deployed with this node configuration. A pod always contains a single running instance of Couchbase Server.

...
    pod:
      couchbaseEnv:
        CB_ENV_VAR: value
      resources:
        limits:
          cpu: 4GHz
          memory: 8GiB
          storage: 100GiB
        requests:
          cpu: 2GHz
          memory: 8GiB
          storage: 50GiB
      labels:
        couchbase_services: all
      nodeSelector:
        instanceType: large
      tolerations:
        - key: app
          operator: Equal
          value: cbapp
          effect: NoSchedule
couchbaseEnv

This field specifies the environment variables (as key-values pairs) that should be set when the pod is started. The key in this case is the environment variable name and the value is the value of the environment variable. This section is optional.

Field rules: The value of this field cannot be changed after a server has been defined.

Resources
...
    resources:
      limits:
        cpu: 2GHz
        memory: 8GiB
        storage: 100GiB
      requests:
        cpu: 1.5GHz
        memory: 8GiB
        storage: 50GiB
...

limits

This field lets you reserve resources on a specific node. It defines the maximum amount of CPU, memory, and storage the pods created in this node specification will reserve.

requests

This field lets you reserve resources on a specific node. The requests section defines the minimum amount of CPU, memory, and storage the pods created in this node specification will reserve.

See the Kubernetes documentation for further information about managing compute resources.

labels

Labels are key-value pairs that are attached to objects in Kubernetes. They are intended to specify identifying attributes of objects that are meaningful to the user and do not directly imply semantics to the core system. Labels can be used to organize and select subsets of objects. They do not need to be unique across multiple objects. This section is optional.

Labels added in this section will apply to all pods added in this cluster. Note that by default we add the following labels to each pod, which should not be overridden.

app:couchbase
couchbase_cluster:<metadata:name>

In the sample configuration file referenced in this topic, the label would be couchbase_cluster:cb-example.

The label for the first pod is of the format: couchbase_node: <metadata:name>-<gen node id>.

In the sample configuration file referenced in this topic, the label for the first pod would be couchbase_node:cb-example-0000.

For more information, see the Kubernetes documentation about labels.

Field rules: The value of this field cannot be changed after a server has been defined.

nodeSelector

This field specifies a key-value map of the constraints on node placement for pods. For a pod to be eligible to run on a node, the node must have each of the indicated key-value pairs as labels (it can have additional labels as well). If this section is not specified, then Kubernetes will place the pod on any available node. For more information, see the Kubernetes documentation about label selectors.

Field rules: The value of this field cannot be changed after a server has been defined.

tolerations

This field specifies conditions upon which a node should not be selected when deploying a pod. From the sample configuration file referenced in this topic, you can see that any node with a label app:cbapp should not be allowed to run the pod defined in this node specification. You might do this if you have nodes dedicated for running an application using Couchbase where you don’t want the database and application to be running on the same node. For more information about tolerations, see the Kubernetes documentation on taints and tolerations. The tolerations section is optional.

Field rules: The value of this field cannot be changed after a server has been defined.