Bootstrap requests
Bootstrap requests
| Method | Path | Description |
|---|---|---|
| GET | /v1/boostrap |
Get the local node's bootstrap status |
| POST | /v1/bootstrap/{action} |
Initiate bootstrapping |
Get bootstrap status
GET /v1/bootstrap
Get the local node's bootstrap status.
This request is accepted as soon the cluster software is installed and before the node is part of an active cluster.
Once the node is part of an active cluster, authentication is required.
Request
Example HTTP request
GET /bootstrap
Headers
| Key | Value | Description |
|---|---|---|
| Accept | application/json | Accepted media type |
Response
The JSON response object contains a bootstrap_status object and a local_node_info object.
The bootstrap_status object contains the following information:
| Field | Description |
|---|---|
| state | Current bootstrap state.idle: No bootstrapping started.initiated: Bootstrap request received.creating_cluster: In the process of creating a new cluster.recovering_cluster: In the process of recovering a cluster.joining_cluster: In the process of joining an existing cluster.error: The last bootstrap action failed.completed: The last bootstrap action completed successfully. |
| start_time | Bootstrap process start time |
| end_time | Bootstrap process end time |
| error_code | If state is error, this error code describes the type of error encountered. |
| error_details | An error-specific object that may contain additional information about the error. A common field in use is message which provides a more verbose error message. |
The local_node_info object is a subset of a node object that provides information about the node configuration.
Example JSON body
{
"bootstrap_status": {
"start_time": "2014-08-29T11:19:49Z",
"end_time": "2014-08-29T11:19:49Z",
"state": "completed"
},
"local_node_info": {
"uid": 3,
"software_version": "0.90.0-1",
"cores": 2,
"ephemeral_storage_path": "/var/opt/redislabs/tmp",
"ephemeral_storage_size": 1018889.8304,
"os_version": "Ubuntu 14.04 LTS",
"persistent_storage_path": "/var/opt/redislabs/persist/redis",
"persistent_storage_size": 1018889.8304,
"total_memory": 24137,
"uptime": 50278,
"available_addrs": [{
"address": "172.16.50.122",
"format": "ipv4",
"if_name": "eth0",
"private": true
},
{
"address": "10.0.3.1",
"format": "ipv4",
"if_name": "lxcbr0",
"private": true
},
{
"address": "172.17.0.1",
"format": "ipv4",
"if_name": "docker0",
"private": true
},
{
"address": "2001:db8:0:f101::1",
"format": "ipv6",
"if_name": "eth0",
"private": false
}]
}
}
Error codes
| Code | Description |
|---|---|
| config_error | An error related to the bootstrap configuration provided (e.g. bad JSON). |
| connect_error | Failed to connect to cluster (e.g. FQDN DNS could not resolve, no/wrong node IP provided, etc. |
| access_denied | Invalid credentials supplied. |
| invalid_license | The license string provided is invalid. Additional info can be fetched from the error_details object, which includes the violation code in case the license is valid but its terms are violated. |
| repair_required | Cluster is in degraded mode and can only accept replacement nodes. When this happens, error_details contains two fields: failed_nodes and replace_candidate. The failed_nodes field is an array of objects, each describing a failed node with at least a uid field and an optional rack_id. replace_candidate is the UID of the node most suitable for replacement. |
| insufficient_node_memory | An attempt to replace a dead node fails because the replaced node does not have enough memory. When this happens, error_details contains a required_memory field which indicates the node memory requirement. |
| insufficient_node_flash | An attempt to replace a dead node fails because the replaced node does not have enough flash. When this happens, error_details contains a required_flash field which indicates the node flash requirement. |
| time_not_sync | An attempt to join a node with system time not synchronized with the rest of the cluster. |
| rack_id_required | An attempt to join a node with no rack_id in a rack-aware cluster. In addition, a current_rack_ids field will include an array of currently used rack ids. |
| socket_directory_mismatch | An attempt to join a node with a socket directory setting that differs from the cluster |
| node_config_mismatch | An attempt to join a node with a configuration setting (e.g. confdir, osuser, installdir) that differs from the cluster |
| path_error | A needed path does not exist or is not accessable. |
| internal_error | A different, unspecified internal error was encountered. |
Status codes
| Code | Description |
|---|---|
| 200 OK | No error |
Start bootstrapping
POST /v1/bootstrap/{action}
Initiate bootstrapping.
The request must contain a bootstrap configuration JSON object, as described in Object attributes or a minimal subset.
Bootstrapping is permitted only when the current bootstrap state is
idle or error (in which case the process will restart with the new
configuration).
This request is asynchronous - once the request has been accepted, the caller is expected to poll bootstrap status while waiting for it to complete.
Request
Example HTTP request
POST /bootstrap/create_cluster
Example JSON body
Join cluster
{
"action": "join_cluster",
"cluster": {
"nodes":[ "1.1.1.1", "2.2.2.2" ]
},
"node": {
"paths": {
"persistent_path": "/path/to/persistent/storage",
"ephemeral_path": "/path/to/ephemeral/storage",
"bigstore_path": "/path/to/bigstore/storage"
},
"bigstore_driver": "speedb",
"identity": {
"addr":"1.2.3.4",
"external_addr":["2001:0db8:85a3:0000:0000:8a2e:0370:7334", "3.4.5.6"]
}
},
"credentials": {
"username": "my_username",
"password": "my_password"
}
}
Create cluster
{
"action": "create_cluster",
"cluster": {
"nodes": [],
"name": "my.cluster"
},
"node": {
"paths": {
"persistent_path": "/path/to/persistent/storage",
"ephemeral_path": "/path/to/ephemeral/storage",
"bigstore_path": "/path/to/bigredis/storage"
},
"identity": {
"addr":"1.2.3.4",
"external_addr":["2001:0db8:85a3:0000:0000:8a2e:0370:7334", "3.4.5.6"]
},
"bigstore_driver": "rocksdb"
},
"license": "----- LICENSE START -----\ndi+iK...KniI9\n----- LICENSE END -----\n",
"credentials": {
"username": "my_username",
"password": "my_password"
}
}
Headers
| Key | Value | Description |
|---|---|---|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |
Request body
Include a bootstrap object in the request body.
Response
Status codes
| Code | Description |
|---|---|
| 200 OK | Request received and processing begins. |
| 409 Conflict | Bootstrap already in progress (check state) |