asensei/couchbase-cluster-manager repository overview

⁠couchbase-cluster-manager

Docker container for Couchbase Server cluster provisioning and configuration.

⁠Overview

Couchbase Cluster Manager is a Docker container running an application written in Swift. It's purpose is to automatically manage a cluster of Couchbase Server nodes running on a Docker swarm.

⁠Features

• Automatically provision a new cluster from scratch.
• Add nodes to a cluster.
• Remove failed nodes from a cluster.
• Rebalance the cluster.

⁠How it works

Glossary:

• Node: a couchbase server instance.
• Service: a docker swarm service, running a couchbase server container (a node).

Couchbase Cluster Manager communicates directly with Docker Swarm and retrieves a list of running services at regular intervals (CCM_INTERVAL). The list is then filtered based on its com.ccm.cluster label to match the manager's CCM_NAME environment variable. It then proceeds to find an already provisioned node, if none is found a new cluster get initialized using the configuration specified on the container environment. At this stage a bucket named CCM_BUCKET_NAME and a sync gateway user CCM_SG_USERNAME / CCM_SG_PASSWORD are created, if defined in the configuration.

Couchbase Cluster Manager now has access to a provisioned node in the cluster, and it proceeds to retrieve a list of well known nodes, in order to work out which ones have been removed and which ones have to be added. It does this, comparing the hostnames on the service list with the node's hostnames.

At this point, nodes matching services that are no longer presents on the Swarm are failed over, meanwhile services running on the Swarm, but not matching any node, are added to the cluster. Once all nodes are processed a rebalance is triggered (if needed).

Note: Couchbase Cluster Manager must run on a docker swarm manager (constraints: [node.role == manager]) and and must bind to /var/run/docker.sock in order to communicate with Docker Swarm and being able to retrieve a list of services.

⁠Configuration

⁠Container Environment Variables

⁠Service Labels

⁠Docker Compose

The following stack will start two couchbase server nodes and one couchbase-cluster-manager.

docker-compose.yml

version: '3.3'
services:

  cbs-01:
    image: couchbase/server:community-5.0.0
    networks:
      default:
        aliases:
          - cbs-01.mycluster
    deploy:
      labels:
        com.ccm.cluster: "mycluster"
        com.ccm.hostname: "cbs-01.mycluster"
        com.ccm.services: "data,index,query,fts"

  cbs-02:
    image: couchbase/server:community-5.0.0
    networks:
      default:
        aliases:
          - cbs-02.mycluster
    deploy:
      labels:
        com.ccm.cluster: "mycluster"
        com.ccm.hostname: "cbs-02.mycluster"
        com.ccm.services: "data,index,query,fts"

  cbs-cluster-manager:
    image: asensei/couchbase-cluster-manager
    environment:
      - CCM_NAME=mycluster
      - CCM_MEMORY_QUOTA=512
      - CCM_INDEX_MEMORY_QUOTA=256
      - CCM_FTS_MEMORY_QUOTA=256
      - CCM_USERNAME=administrator
      - CCM_PASSWORD=password
      - CCM_BUCKET_NAME=default
      - CCM_BUCKET_MEMORY_QUOTA=512
      - CCM_SG_USERNAME=syncgateway
      - CCM_SG_PASSWORD=password
      - CCM_INTERVAL=300
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    deploy:
      placement:
        constraints: [node.role == manager]

  networks:
    default: