Initializing a Cluster

reference

A cluster can be initialized and provisioned, by means of a single call to the REST API.

HTTP Method and URI

POST /clusterInit

Description

Initializes and provisions a cluster. The POST /clusterInit method and URI thereby achieve as a single call the combined effectiveness of several other calls that each perform only a part of the initialization and provisioning sequence. These other calls are all described elsewhere in this section, as Initializing a Node, Establishing Credentials, Naming a Node, Configuring Memory, Assigning Services, and Naming a Cluster.

Note that the POST /clusterInit method and URI allow the specifying of several parameters in addition to those supported by the other calls. All parameters are listed and described below.

Curl Syntax

curl -X POST http://<ip-address-or-domain-name>:8091/clusterInit
  -d hostname=<ip-address-or-domain-name>
  -d username=<username>
  -d password=<password>
  -d data_path=<data-path>
  -d index_path=<index-path>
  -d cbas_path=<analytics-path>
  -d eventing_path=<eventing-path>
  -d java_home=<jre-path>
  -d sendStats=true
  -d clusterName=<cluster-name>
  -d services=<list-of-service-names>
  -d memoryQuota=<integer>
  -d queryMemoryQuota=<integer>
  -d indexMemoryQuota=<integer>
  -d eventingMemoryQuota=<integer>
  -d ftsMemoryQuota=<integer>
  -d cbasMemoryQuota=<integer>
  -d afamily=[ 'ipv4' | 'ipv6' ]
  -d afamilyOnly=[ true | false ]
  -d nodeEncryption=[ 'on' | 'off' ]
  -d indexerStorageMode=[ 'plasma' | 'magma' ]
  -d port='SAME'
  -d allowedHosts=<list-of-naming-conventions>

The parameters and arguments are listed below:

hostname. The IP address or domain name that will be the name of the node established as a single-node cluster. This parameter is optional: the default value is 127.0.0.1.
username. A string that will be the username for the new cluster. This parameter must be specified.
password. A string that will be the password for the new cluster. This parameter must be specified.
data_path, index_path, cbas_path, eventing_path. Paths for the storage of data to be used by the Data, Index, Analytics, and Eventing Services. All paths must be writable by user couchbase. These parameters are optional. For the default values, see Initializing a Node.
java_home. Location of the JRE to be used by the Analytics Service. The specified path must be writable by user couchbase. This parameter is optional. There is no default value.
sendStats. Enables or disables Couchbase Server software update notifications and sharing of system performance information with Couchbase. See the update-notifications option in the cluster-init command line interface reference for details of what sendStats shares. It’s always set to true for Couchbase Server Community Edition. In Couchbase Server Enterprise Edition, you can set the value to the default true or false.
cluster_name. A name for the cluster. This name is for convenience of identification, and will not be used for network access. This parameter is optional. There is no default value.
services. A list of the services to be hosted on the cluster. The list must consist of one or more of the following: kv (Data Service), n1ql (Query Service), index (Index Service), fts (Search Service), eventing (Eventing Service), cbas (Analytics Service), backup (Backup Service). Each name must be separated from the following name with a comma.

Each service is allocated a default amount of memory, unless custom allocations have been made. See Configuring Memory for information on allocating memory per service, and on the default minimum values per service.

This parameter must be specified. The value must be at least one service: there is no default.
memoryQuota, queryMemoryQuota, indexMemoryQuota, eventingMemoryQuota, ftsMemoryQuota, cbasMemoryQuota. The memory quotas for the Data, Query, Index, Eventing, Search, and Analytics Services. (The Backup Service does not require a memory allocation.)

Each quota is specified as an integer. If no custom quota is specified for one or more services, those services retain the default allocations: these are, for the Data Service 256 Mb; for the Search Service 256 Mb; for the Index Service 512 Mb; for the Eventing Service 256 Mb; for the Analytics Service 1024 Mb; and for the Query Service 0 Mb, indicating that there is no specified quota. Note that for most services, the minimum allowed allocation is 256 Mb: for the Analytics Service, the minimum allowed allocation is 1024 Mb, and for the Query Service, the minimum allowed allocation is 0 Mb.

For information on the maximum memory allocation permitted for a node, see Service Memory Quotas.
afamily. The IP address-family principally to be used by the cluster. This parameter is optional. Either ipv4 (the default) or ipv6 can be specified.
afamilyOnly. Whether only the address-family specified by afamily should be used. This parameter is optional. The value can be true or false (the default). For information, see Manage Address Families.
nodeEncryption. Whether node-to-node encryption should be switched on for the cluster. This parameter is optional. Value can be on or off (the default). For information, see Node-to-Node Encryption.
indexerStorageMode. This can be plasma (the default) or magma. For information, see Storage Settings. This parameter is optional.
port. The number of the port that the new, single-node cluster will use as its administration port for unencrypted traffic. The value SAME specifies the standard port-number, which is 8091. This parameter must be explicitly specified, even if SAME is to be used.
allowedHosts. A comma-separated list of the naming conventions that determine which hosts are allowed to be added or joined to the new cluster. The default is "*", which determines that any hostname is acceptable. For information, see Restrict Node-Addition. This parameter is optional, and is available only in Couchbase Server Version 7.1.1+.

Responses

Success returns 200 OK. If a directory is not writable by user couchbase, 400 Bad Request is returned, with a message such as: ["Could not set analytics storage. All directories must be writable by 'couchbase' user."]. An incorrectly specified URL or data parameter returns 404 Object Not Found.

Example

The following example creates a new, single-node cluster:

curl -v -X POST http://10.144.231.104:8091/clusterInit \
-d "hostname=com.test.ubuntu" \
-d "dataPath=%2Fopt%2Fcouchbase%2Fvar%2Flib%2Fcouchbase%2Fdata" \
-d "indexPath=%2Fopt%2Fcouchbase%2Fvar%2Flib%2Fcouchbase%2Fdata" \
-d "eventingPath=%2Fopt%2Fcouchbase%2Fvar%2Flib%2Fcouchbase%2Fdata" \
-d "analyticsPath=%2Fopt%2Fcouchbase%2Fvar%2Flib%2Fcouchbase%2Fdata" \
-d "javaHome=" \
-d "sendStats=true" \
-d "services=kv%2Cn1ql" \
-d "clusterName=FourthCluster" \
-d "memoryQuota=256" \
-d "afamily=ipv4" \
-d "afamilyOnly=false" \
-d "nodeEncryption=off" \
-d "username=Administrator" \
-d "password=password" \
-d "port=SAME" \
-d "allowedHosts=*.test.ubuntu,127.0.0.1"

Success returns a confirmation such as the following:

{"newBaseUri":"http://10.144.231.104:8091/"}