Setting a Replica-Minimum

March 16, 2025

+ 12

A required minimum can be established for the number of replicas configured for a bucket.

HTTP Methods and URIs

POST /settings/dataService

GET /settings/dataService

Description

Used with the POST method, the URI specifies an integer that establishes a required minimum for the number of replicas subsequently configured for every new bucket. Existing buckets are unaffected, and may continue to be used with their existing replica-configuration, even if the number is below the new minimum.

Used with the GET method, the URI returns the current minimum.

Curl Syntax

curl -X POST http://<ip-address-or-domain-name>:8091/settings/dataService
  -u <username>:<password>
  -d minReplicasCount=<integer>

curl -X GET http://<ip-address-or-domain-name>:8091/settings/dataService
  -u <username>:<password>

The integer specified as the value of the minReplicasCount parameter must be an integer from 0 to 3. This integer establishes a minimum for the number of replicas that may be configured.

Responses

Failure to authenticate returns 401 Unauthorized. An incorrectly expressed URI returns 404 Object Not Found. Specifying a minimum outside the required range returns 400 Bad Request, and the following object: {"errors":{"minReplicasCount":"The value must be in range from 0 to 3"}}.

Examples

The following example establishes 2 as the minimum number of replicas required for each subsequently created bucket.

curl -v -X POST http://localhost:8091/settings/dataService -d minReplicasCount=2 -u Administrator:password

If successful, the call returns the following confirmation:

{"minReplicasCount":2}

The current established minimum number can be returned as follows:

curl -v -X GET http://localhost:8091/settings/dataService -u Administrator:password

Again, if the call is successful, the following confirmation is returned:

{"minReplicasCount":2}

In consequence of the established minimum, any attempt to create a bucket with a number of replicas that is less than the minimum generates an error, and the bucket is not created. The following example attempts to create a bucket with only 1 replica, while the established minimum is 2. The output is piped to the jq program, to facilitate readability:

curl -v -X POST http://localhost:8091/pools/default/buckets -d name=testBucket1 -d ramQuota=100 -d replicaNumber=1 -u Administrator:password  | jq '.'

This call fails with 400 Bad Request, and returns the following summary:

{
  "errors": {
    "replicaNumber": "Replica number must be equal to or greater than 2"
  },
  "summaries": {
    "ramSummary": {
      "total": 1610612736,
      "otherBuckets": 0,
      "nodesCount": 3,
      "perNodeMegs": 100,
      "thisAlloc": 314572800,
      "thisUsed": 0,
      "free": 1296039936
    },
    "hddSummary": {
      "total": 396484890624,
      "otherData": 17181011926,
      "otherBuckets": 0,
      "thisUsed": 0,
      "free": 379303878698
    }
  }
}

The value of replicaNumber is a string describing the error. The summaries subdocument contains two objects: ramSummary and hddSummary, which respectively describe quota and usage for memory and disk. Figures are in Bytes, unless otherwise stated.