Skip to content

Commit 81c3bbd

Browse files
rrelledgedwdougherty
rrelledge
and
dwdougherty
authored
RS: Added missing CRDB parameters to crdb-cli and REST API references (#1775)
* DOC-5354 Added missing parameters for crdb-cli crdb create and more details/descriptions for optional parameters * DOC-5354 Added some examples of CRDB instance parameters * DOC-5354 Edited optional instance parameters for crd-cli crdb create * DOC-5354 Added missing instance parameters and details to crdb-cli crdb add-instance reference * DOC-5354 Copied missing instance parameters and details to RS 7.4 crdb-cli references * DOC-5354 Copied missing instance parameters and details to RS 7.8 crdb-cli references * DOC-5354 Added missing CRDB requests and fields to RS REST API reference * DOC-5354 Copied missing CRDB requests and fields to RS 7.8 and 7.4 REST API references * Apply suggestions from code review Co-authored-by: David Dougherty <[email protected]> --------- Co-authored-by: David Dougherty <[email protected]>
1 parent 93d6e7b commit 81c3bbd

File tree

24 files changed

+416
-55
lines changed

24 files changed

+416
-55
lines changed

‎content/operate/rs/7.4/references/cli-utilities/crdb-cli/crdb/add-instance.md‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,19 +15,20 @@ Adds a peer replica to an existing Active-Active database in order to host the d
1515

1616
```sh
1717
crdb-cli crdb add-instance --crdb-guid <guid>
18-
--instance fqdn=<cluster_fqdn>,username=<username>,password=<password>[,url=<url>,replication_endpoint=<endpoint>]
19-
[ --compression <0-6> ]
20-
[ --no-wait ]
18+
--instance fqdn=<cluster_fqdn>,username=<username>,password=<password>[,url=https://<hostname-or-IP>:9443,replication_endpoint=<hostname-or-IP>:<port>,replication_tls_sni=<hostname>]
19+
[--compression <0-6>]
20+
[--wait | --no-wait]
2121
```
2222

2323
### Parameters
2424

2525
| Parameter | Value | Description |
2626
|-----------|---------|-------------|
2727
| crdb-guid | string | The GUID of the database (required) |
28-
| instance | strings | The connection information for the new participating cluster (required) |
29-
| compression | 0-6 | The level of data compression: 0=Compression disabled <br> <br> 6=High compression and resource load (Default: 3) |
30-
| no-wait | | Does not wait for the task to complete |
28+
| instance fqdn=\<cluster_fqdn\>,username=\<username\>,password=\<password\>,url=https://\<hostname-or-IP\>:9443,replication_endpoint=\<hostname-or-IP\>:\<port\>,replication_tls_sni=\<hostname\> | strings | The connection information for the new participating cluster (required)<br/><br/>**Required:**<br/>• `fqdn` - Cluster fully qualified domain name<br/>• `username` - Cluster username<br/>• `password` - Cluster password<br/><br/>**Optional:**<br/>• `url` - URL to access the cluster's REST API<br/>• `replication_endpoint` - Address to access the database instance for peer replication<br/>• `replication_tls_sni` - Cluster [Server Name Indication (SNI)](https://en.wikipedia.org/wiki/Server_Name_Indication) hostname for TLS connections |
29+
| compression | 0-6 | The level of data compression: <br /><br > 0 = No compression <br /><br > 6 = High compression and resource load (Default: 3) |
30+
| wait | | Prevents `crdb-cli` from running another command before this command finishes |
31+
| no-wait | | `crdb-cli` can run another command before this command finishes |
3132

3233
### Returns
3334

‎content/operate/rs/7.4/references/cli-utilities/crdb-cli/crdb/create.md‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,10 +16,10 @@ Creates an Active-Active database.
1616
```sh
1717
crdb-cli crdb create --name <name>
1818
--memory-size <maximum_memory>
19-
--instance fqdn=<cluster_fqdn>,username=<username>,password=<password>[,url=<url>,replication_endpoint=<endpoint>]
20-
--instance fqdn=<cluster_fqdn>,username=<username>,password=<password>[,url=<url>,replication_endpoint=<endpoint>]
19+
--instance fqdn=<cluster1.example.com>,username=<username>,password=<password>[,url=https://<hostname-or-IP>:9443,replication_endpoint=<hostname-or-IP>:<port>,replication_tls_sni=<hostname>]
20+
--instance fqdn=<cluster2.example.com>,username=<username>,password=<password>[,url=https://<hostname-or-IP>:9443,replication_endpoint=<hostname-or-IP>:<port>,replication_tls_sni=<hostname>]
2121
[--port <port_number>]
22-
[--no-wait]
22+
[--wait | --no-wait]
2323
[--default-db-config <configuration>]
2424
[--default-db-config-file <filename>]
2525
[--compression <0-6>]
@@ -31,8 +31,11 @@ crdb-cli crdb create --name <name>
3131
[--shards-count <number_of_shards>]
3232
[--shard-key-regex <regex_rule>]
3333
[--oss-cluster { true | false } ]
34+
[--oss-sharding { true | false } ]
3435
[--bigstore { true | false }]
3536
[--bigstore-ram-size <maximum_memory>]
37+
[--eviction-policy { noeviction | allkeys-lru | allkeys-lfu |allkeys-random | volatile-lru | volatile-lfu | volatile-random | volatile-ttl }]
38+
[--proxy-policy { all-nodes | all-master-shards | single }]
3639
[--with-module name=<module_name>,version=<module_version>,args=<module_args>]
3740
```
3841
@@ -50,11 +53,12 @@ Before you create an Active-Active database, you must have:
5053
|---------------------------------------------------------------------------------------|-------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
5154
| name \<CRDB_name\> | string | Name of the Active-Active database (required) |
5255
| memory-size \<maximum_memory\> | size in bytes, kilobytes (KB), or gigabytes (GB) | Maximum database memory (required) |
53-
| instance<br/>&nbsp;&nbsp; fqdn=\<cluster_fqdn\>,<br/>&nbsp;&nbsp; username=\<username\>,<br/>&nbsp;&nbsp; password=\<password\> | strings | The connection information for the participating clusters (required for each participating cluster) |
56+
| instance fqdn=\<cluster_fqdn\>,username=\<username\>,password=\<password\>,url=https://\<hostname-or-IP\>:9443,replication_endpoint=\<hostname-or-IP\>:\<port\>,replication_tls_sni=\<hostname\> | strings | The connection information for the participating clusters (required for each participating cluster)<br/><br/>**Required:**<br/>• `fqdn` - Cluster fully qualified domain name<br/>• `username` - Cluster username<br/>• `password` - Cluster password<br/><br/>**Optional:**<br/>• `url` - URL to access the cluster's REST API<br/>• `replication_endpoint` - Address to access the database instance for peer replication<br/>• `replication_tls_sni` - Cluster [Server Name Indication (SNI)](https://en.wikipedia.org/wiki/Server_Name_Indication) hostname for TLS connections |
5457
| port \<port_number\> | integer | TCP port for the Active-Active database on all participating clusters |
5558
| default-db-config \<configuration\> | string | Default database configuration options |
5659
| default-db-config-file \<filename\> | filepath | Default database configuration options from a file |
57-
| no-wait | | Prevents `crdb-cli` from running another command before this command finishes |
60+
| wait | | Prevents `crdb-cli` from running another command before this command finishes |
61+
| no-wait | | `crdb-cli` can run another command before this command finishes |
5862
| compression | 0-6 | The level of data compression: <br /><br > 0 = No compression <br /><br > 6 = High compression and resource load (Default: 3) |
5963
| causal-consistency | true <br/> false (*default*) | [Causal consistency]({{< relref "/operate/rs/7.4/databases/active-active/causal-consistency.md" >}}) applies updates to all instances in the order they were received |
6064
| password \<password\> | string | Password for access to the database |

‎content/operate/rs/7.4/references/rest-api/objects/crdb/_index.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,5 +26,11 @@ An object that represents an Active-Active database.
2626
"bdb_uid": string,
2727
"id": integer
2828
}, ...] {{</code>}} | Mapping of instance IDs for local databases to local BDB IDs |
29+
| managed_by | string | The component that manages the Active-Active database |
30+
| modules | {{<code>}}[{
31+
"featureset_version": integer,
32+
"module_name": string
33+
}, ...] {{</code>}} | Modules used by the Active-Active database |
2934
| name | string | Name of Active-Active database |
3035
| protocol_version | integer | Active-Active database active protocol version |
36+
| volatile_config_fields | array of strings | A list of database configuration fields that will be set even if unchanged |

‎content/operate/rs/7.4/references/rest-api/objects/crdb_task.md‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,12 +15,24 @@ An object that represents an Active-Active (CRDB) task.
1515

1616
| Name | Type/Value | Description |
1717
|------|------------|-------------|
18-
| id | string | CRDB task ID (read only) |
18+
| id | string | CRDB task ID (read-only) |
1919
| crdb_guid | string | Globally unique Active-Active database ID (GUID) (read-only) |
20+
| ended | string | Timestamp when the task ended (read-only) |
2021
| errors | {{<code>}}
2122
[{
2223
"cluster_name": string,
2324
"description": string,
2425
"error_code": string
2526
}, ...] {{</code>}} | Details for errors that occurred on a cluster |
26-
| status | 'queued' <br />'started' <br />'finished' <br />'failed' | CRDB task status (read only) |
27+
| operation | string | The operation that is running (read-only) |
28+
| progress | {{<code>}}
29+
{
30+
"clusters": [{
31+
"name": string,
32+
"progress": string
33+
}, ...],
34+
"worker": string
35+
} {{</code>}} | • `name`: The instance cluster name<br />• `progress`: The step the instance coordinator is running<br />• `worker`: The step the worker is running |
36+
| started | string | Timestamp when the task started (read-only) |
37+
| status | 'queued' <br />'started' <br />'finished' <br />'failed' | CRDB task status (read-only) |
38+
| worker_name | string | The worker that runs the task (read-only) |

‎content/operate/rs/7.4/references/rest-api/requests/crdb_tasks/_index.md‎

Lines changed: 82 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,36 @@ url: '/operate/rs/7.4/references/rest-api/requests/crdb_tasks/'
1515

1616
| Method | Path | Description |
1717
|--------|------|-------------|
18+
| [GET](#get-all-crdb_tasks) | `/v1/crdb_tasks` | Get all running tasks |
1819
| [GET](#get-crdb_task) | `/v1/crdb_tasks/{task_id}` | Get the status of an executed task |
20+
| [POST](#post-crdb_task-cancel) | `/v1/crdb_tasks/{task_id}/actions/cancel` | Cancel a running or queued task |
21+
22+
## Get all running tasks {#get-all-crdb_tasks}
23+
24+
```sh
25+
GET /v1/crdb_tasks
26+
```
27+
28+
Get all running tasks.
29+
30+
### Request {#get-all-request}
31+
32+
#### Example HTTP request
33+
34+
```sh
35+
GET /v1/crdb_tasks
36+
```
37+
38+
### Response {#get-all-response}
39+
40+
Returns a JSON array of [CRDB task objects]({{< relref "/operate/rs/7.4/references/rest-api/objects/crdb_task" >}}).
41+
42+
#### Status codes {#get-all-status-codes}
43+
44+
| Code | Description |
45+
|------|-------------|
46+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | A list of running tasks. |
47+
| [401 Unauthorized](https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized) | Unauthorized request. Invalid credentials. |
1948

2049
## Get task status {#get-crdb_task}
2150

@@ -43,6 +72,12 @@ The status of a completed task is kept for 500 seconds by default.
4372
|-------|------|-------------|
4473
| task_id | string | Task ID |
4574

75+
#### Query parameters
76+
77+
| Field | Type | Description |
78+
|-------|------|-------------|
79+
| verbose | boolean | Return detailed task information (optional) |
80+
4681
### Response {#get-response}
4782

4883
Returns a [CRDB task object]({{< relref "/operate/rs/7.4/references/rest-api/objects/crdb_task" >}}).
@@ -51,6 +86,50 @@ Returns a [CRDB task object]({{< relref "/operate/rs/7.4/references/rest-api/obj
5186

5287
| Code | Description |
5388
|------|-------------|
54-
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Task status. |
55-
| [401 Unauthorized](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) | Unauthorized request. Invalid credentials |
56-
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Task not found. |
89+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Task status. |
90+
| [401 Unauthorized](https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized) | Unauthorized request. Invalid credentials. |
91+
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Task not found. |
92+
93+
## Cancel task {#post-crdb_task-cancel}
94+
95+
```sh
96+
POST /v1/crdb_tasks/{task_id}/actions/cancel
97+
```
98+
99+
Gracefully cancels a running or queued task.
100+
101+
A task that already reached the commit phase cannot be canceled.
102+
103+
### Request {#post-cancel-request}
104+
105+
#### Example HTTP request
106+
107+
```sh
108+
POST /v1/crdb_tasks/1/actions/cancel
109+
```
110+
111+
#### URL parameters
112+
113+
| Field | Type | Description |
114+
|-------|------|-------------|
115+
| task_id | string | Task ID |
116+
117+
#### Query parameters
118+
119+
| Field | Type | Description |
120+
|-------|------|-------------|
121+
| force | boolean | Cancel even when the task is during commit. **WARNING**: Can break the CRDB in CCS, use with caution! (optional) |
122+
123+
### Response {#post-cancel-response}
124+
125+
Returns a success message.
126+
127+
#### Status codes {#post-cancel-status-codes}
128+
129+
| Code | Description |
130+
|------|-------------|
131+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | The request has been accepted. |
132+
| [401 Unauthorized](https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized) | Unauthorized request. Invalid credentials. |
133+
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Task not found. |
134+
| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | Task cannot be canceled. |
135+
| [409 Conflict](https://www.rfc-editor.org/rfc/rfc9110.html#name-409-conflict) | Failed to cancel task. |

‎content/operate/rs/7.4/references/rest-api/requests/crdbs/_index.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -174,6 +174,12 @@ Create a new Active-Active database.
174174
| X-Task-ID | string | Specified task ID |
175175
| X-Result-TTL | integer | Time (in seconds) to keep task result |
176176

177+
#### Query parameters
178+
179+
| Field | Type | Description |
180+
|-------|------|-------------|
181+
| dry_run | boolean | Validate the request without creating the database (optional) |
182+
177183
#### Request body
178184

179185
Include a [CRDB object]({{< relref "/operate/rs/7.4/references/rest-api/objects/crdb" >}}), which defines the Active-Active database, in the request body.

‎content/operate/rs/7.4/references/rest-api/requests/crdbs/flush.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,12 @@ PUT /v1/crdbs/552bbccb-99f3-4142-bd17-93d245f0bc79/flush
4545
|-------|------|-------------|
4646
| crdb_guid | string | Globally unique Active-Active database ID (GUID) |
4747

48+
#### Query parameters
49+
50+
| Field | Type | Description |
51+
|-------|------|-------------|
52+
| async_flush | boolean | Perform asynchronous flush operation (optional) |
53+
4854
### Response {#put-response}
4955

5056
Returns a [CRDB task object]({{< relref "/operate/rs/7.4/references/rest-api/objects/crdb_task" >}}).

‎content/operate/rs/7.4/references/rest-api/requests/crdbs/updates.md‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ Updating default_db_config affects both existing and new instances that may be a
3232

3333
When you update db_config, it changes the configuration of the database that you specify. This field overrides corresponding fields (if any) in default_db_config.
3434

35-
### Request {#post-request}
35+
### Request {#post-request}
3636

3737
#### Example HTTP request
3838

@@ -51,15 +51,21 @@ When you update db_config, it changes the configuration of the database that you
5151
|-------|------|-------------|
5252
| crdb_guid | string | Globally unique Active-Active database ID (GUID) |
5353

54+
#### Query parameters
55+
56+
| Field | Type | Description |
57+
|-------|------|-------------|
58+
| dry_run | boolean | Validate the request without applying changes (optional) |
59+
5460
#### Request body
5561

5662
Include a [CRDB modify_request object]({{< relref "/operate/rs/7.4/references/rest-api/objects/crdb/modify_request" >}}) with updated fields in the request body.
5763

58-
### Response {#post-response}
64+
### Response {#post-response}
5965

6066
Returns a [CRDB task object]({{< relref "/operate/rs/7.4/references/rest-api/objects/crdb_task" >}}).
6167

62-
### Status codes {#post-status-codes}
68+
### Status codes {#post-status-codes}
6369

6470
| Code | Description |
6571
|------|-------------|

‎content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/add-instance.md‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,19 +15,20 @@ Adds a peer replica to an existing Active-Active database in order to host the d
1515

1616
```sh
1717
crdb-cli crdb add-instance --crdb-guid <guid>
18-
--instance fqdn=<cluster_fqdn>,username=<username>,password=<password>[,url=<url>,replication_endpoint=<endpoint>]
19-
[ --compression <0-6> ]
20-
[ --no-wait ]
18+
--instance fqdn=<cluster_fqdn>,username=<username>,password=<password>[,url=https://<hostname-or-IP>:9443,replication_endpoint=<hostname-or-IP>:<port>,replication_tls_sni=<hostname>]
19+
[--compression <0-6>]
20+
[--wait | --no-wait]
2121
```
2222

2323
### Parameters
2424

2525
| Parameter | Value | Description |
2626
|-----------|---------|-------------|
2727
| crdb-guid | string | The GUID of the database (required) |
28-
| instance | strings | The connection information for the new participating cluster (required) |
29-
| compression | 0-6 | The level of data compression: 0=Compression disabled <br> <br> 6=High compression and resource load (Default: 3) |
30-
| no-wait | | Does not wait for the task to complete |
28+
| instance fqdn=\<cluster_fqdn\>,username=\<username\>,password=\<password\>,url=https://\<hostname-or-IP\>:9443,replication_endpoint=\<hostname-or-IP\>:\<port\>,replication_tls_sni=\<hostname\> | strings | The connection information for the new participating cluster (required)<br/><br/>**Required:**<br/>• `fqdn` - Cluster fully qualified domain name<br/>• `username` - Cluster username<br/>• `password` - Cluster password<br/><br/>**Optional:**<br/>• `url` - URL to access the cluster's REST API<br/>• `replication_endpoint` - Address to access the database instance for peer replication<br/>• `replication_tls_sni` - Cluster [Server Name Indication (SNI)](https://en.wikipedia.org/wiki/Server_Name_Indication) hostname for TLS connections |
29+
| compression | 0-6 | The level of data compression: <br /><br > 0 = No compression <br /><br > 6 = High compression and resource load (Default: 3) |
30+
| wait | | Prevents `crdb-cli` from running another command before this command finishes |
31+
| no-wait | | `crdb-cli` can run another command before this command finishes |
3132

3233
### Returns
3334

0 commit comments

Comments
 (0)