Updating Group Membership
Server group membership is changed by means of the PUT /pools/default/serverGroups
HTTP method and URI.
Description
This changes the membership of the groups that currently exist for the specified cluster. It does not permit the creation, removal, or renaming of groups. Every existing node must be specified once, and thereby assigned to an existing group. Groups to which no nodes are assigned must be specified as empty.
This node-to-group assignment must be specified as a JSON document: when curl
is used, the document can be specified either explicitly, as a parameter-value on the command-line; or as a .json
file.
The request is transactional: it either succeeds completely, or fails without impact.
See Server Group Awareness, for a conceptual overview of groups.
Curl Syntax
curl -d @<jsonInput> -X PUT -u <administrator>:<password> http://<host>:<port>/pools/default/serverGroups?rev=<number>
The syntax includes the following:
-
jsonInput
. The new configuration of nodes and groups, provided as a JSON document. Whencurl
is used, the document can be provided either explicitly, as a parameter-value on the command-line; or as a.json
file. See below for information on format. -
rev=<number>
. The revision number for the existing configuration. This number can be retrieved by means of theGET /pools/default/serverGroups
HTTP method and URI: see Getting Server Group Information. Note that this number changes whenever the configuration changes.
Node-to-Group Assignment
The following JSON document assigns all three of a cluster’s nodes to the first of its two groups, thereby leaving the second group empty.
{ "groups": [ { "nodes": [ {"otpNode": "ns_1@10.143.190.101"}, {"otpNode": "ns_1@10.143.190.102"}, {"otpNode": "ns_1@10.143.190.103"} ], "name": "Group 1", "uri": "/pools/default/serverGroups/0" }, { "nodes": [], "name": "Group 2", "uri": "/pools/default/serverGroups/3b66b3c3177f44a3ffa6771ffeb31f36" } ] }
The value of the groups
key is an array, each of whose elements is an object that corresponds to one of the server groups for the cluster.
Each group must be specified with the following:
-
nodes
. An array of the nodes in the group. Each node is specified with the keyotpNode
and the valuens_1@node-ip-address
. -
uri
. The URI for the server group. This can be retrieved with theGET /pools/default/serverGroups
HTTP method and URI: see Getting Server Group Information. Each URI is terminated with the unique UUID string for the group: for the default group,Group 1
, this is always0
.
Optionally, the name
of the group can be specified.
This must correspond exactly to the current, established name of the group.
This method cannot be used to change that name.
Responses
Success gives 200 OK
, and returns an empty array.
Malformed JSON, or failure to address all existing nodes, groups and group-names accurately, gives 400 BAD REQUEST
, and returns a Bad input
array, containing the submitted JSON document.
Failure to authenticate gives 401 Unauthorized
.
Examples
In the following examples, the cluster is considered to have two groups defined:
-
Group 1 contains nodes
10.143.190.101
and10.143.190.102
. -
Group 2 contains the node
10.143.190.103
.
The JSON document shown above, in Node-to-Group Assignment, can thus be used to locate all nodes in Group 1, leaving Group 2 empty.
The JSON document can be specified as a file, as follows:
curl -d@groupChangeDefinition.json -X PUT \ http://Administrator:password http://10.143.190.101:8091/pools/default/serverGroups?rev=112632175
Alternatively, the JSON document can be provided explicitly, on the command line.
curl -u Administrator:password -X PUT \ http://10.143.190.101:8091/pools/default/serverGroups?rev=112632175 \ -d '{"groups": [{"nodes": [{"otpNode": "ns_1@10.143.190.101"}, {"otpNode": "ns_1@10.143.190.102"}, {"otpNode": "ns_1@10.143.190.103"}], "name": "Group 1", "uri": "/pools/default/serverGroups/0"}, {"nodes": [], "name": "Group 2", "uri": "/pools/default/serverGroups/3b66b3c3177f44a3ffa6771ffeb31f36"}] }'
Each of these commands moves the node 10.143.190.103
into Group 1.
To check results, use the GET /pools/default/serverGroups
HTTP method and URI: see Getting Server Group Information.
See Also
See Getting Server Group Information for getting information on the current node-to-group configuration for the server. See Server Group Awareness, for a conceptual overview of groups. See Manage Groups, for examples of managing groups by means of Couchbase Web Console. See Adding Servers to Server Groups, for information on adding nodes to groups.