Initializing a Cluster
- reference
A cluster can be initialized and provisioned, by means of a single call to the REST API.
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 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 is127.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 usercouchbase
. 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 usercouchbase
. This parameter is optional. There is no default value. -
sendStats
. Whether the cluster should send statistics to Couchbase, for analysis. This parameter is optional. The value can betrue
(the default) orfalse
. -
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
,indexMemoryQuota
,eventingMemoryQuota
,ftsMemoryQuota
,cbasMemoryQuota
. The memory quotas for the Data, Index, Eventing, Search, and Analytics Services. (The Query and Backup Services do 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; and for the Analytics Service 1024 Mb. Note that in each case except the Analytics Service, the minimum allowed allocation is 256 Mb: for the Analytics Service, the minimum allowed allocation is 1024 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. Eitheripv4
(the default) oripv6
can be specified. -
afamilyOnly
. Whether only the address-family specified byafamily
should be used. This parameter is optional. The value can betrue
orfalse
(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 beon
oroff
(the default). For information, see Node-to-Node Encryption. -
indexerStorageMode
. This can beplasma
(the default) ormagma
. 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 valueSAME
specifies the standard port-number, which is8091
. This parameter must be explicitly specified, even ifSAME
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/"}
See Also
An overview of nodes is provided in Nodes. Information on storage and memory-management is provided in Memory and Storage. Node-to-node Encryption is described in Node-to-Node Encryption. Address families are described in Manage Address Families. Index storage modes are explained in Storage Settings.