Skip to content

RS: Cert based auth for CRDB #3756

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kaitlynmichael wants to merge 5 commits into
base: main
Choose a base branch
from
Open

RS: Cert based auth for CRDB #3756

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
9b8dd4c
document control_plane_basic_authentication in rladmin tune reference
kaitlynmichael Aug 5, 2026
04f697c
document the order of operations for disabling basic authentication
kaitlynmichael Aug 6, 2026
2d62f45
document certificate credentials for cluster join and Active-Active
kaitlynmichael Aug 6, 2026
ebad45a
document certificate credentials across the join and Active-Active re…
kaitlynmichael Aug 6, 2026
5baf3bc
fix typo in CRDB cluster info object reference
kaitlynmichael Aug 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions content/operate/rs/references/cli-utilities/crdb-cli/crdb/add-instance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Adds a peer replica to an existing Active-Active database in order to host the d

```sh
crdb-cli crdb add-instance --crdb-guid <guid>
--instance fqdn=<cluster_fqdn>,username=<username>,password=<password>[,url=https://<hostname-or-IP>:9443,replication_endpoint=<hostname-or-IP>:<port>,replication_tls_sni=<hostname>]
--instance fqdn=<cluster_fqdn>,{ username=<username>,password=<password> | client_cert=<cert>,client_key=<key>[,trusted_ca=<ca>] }[,url=https://<hostname-or-IP>:9443,replication_endpoint=<hostname-or-IP>:<port>,replication_tls_sni=<hostname>]
[--compression <0-6>]
[--wait | --no-wait]
```
Expand All @@ -24,7 +24,7 @@ crdb-cli crdb add-instance --crdb-guid <guid>
| Parameter | Value | Description |
|-----------|---------|-------------|
| crdb-guid | string | The GUID of the database (required) |
| 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 |
| 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/>• Either a username and password, or certificate credentials:<br/>&nbsp;&nbsp;- `username` and `password` - Cluster username and password<br/>&nbsp;&nbsp;- `client_cert` and `client_key` - Client certificate and its private key, as PEM strings<br/><br/>Don't provide both for the same cluster. The command fails with `Use either username/password or client_cert/client_key/trusted_ca, not both`.<br/><br/>**Optional:**<br/>• `trusted_ca` - CA that validates the API certificate the peer cluster presents, as a PEM string. Only valid with certificate credentials. If you omit it, the cluster uses the certificates in its `mtls_trusted_ca.pem` file.<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<br/><br/>See [Certificate-based authentication for cluster management]({{<relref "/operate/rs/security/certificates/certificate-based-authentication#certificate-based-authentication-for-cluster-management">}}). |
| compression | 0-6 | The level of data compression: <br /><br > 0 = No compression <br /><br > 6 = High compression and resource load (Default: 3) |
| wait | | Prevents `crdb-cli` from running another command before this command finishes |
| no-wait | | `crdb-cli` can run another command before this command finishes |
Expand Down
14 changes: 11 additions & 3 deletions content/operate/rs/references/cli-utilities/crdb-cli/crdb/create.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ Creates an Active-Active database.
```sh
crdb-cli crdb create --name <name>
--memory-size <maximum_memory>
--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>]
--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>]
--instance fqdn=<cluster1.example.com>,{ username=<username>,password=<password> | client_cert=<cert>,client_key=<key>[,trusted_ca=<ca>] }[,url=https://<hostname-or-IP>:9443,replication_endpoint=<hostname-or-IP>:<port>,replication_tls_sni=<hostname>]
--instance fqdn=<cluster2.example.com>,{ username=<username>,password=<password> | client_cert=<cert>,client_key=<key>[,trusted_ca=<ca>] }[,url=https://<hostname-or-IP>:9443,replication_endpoint=<hostname-or-IP>:<port>,replication_tls_sni=<hostname>]
[--port <port_number>]
[--wait | --no-wait]
[--default-db-config <configuration>]
Expand Down Expand Up @@ -52,7 +52,7 @@ Before you create an Active-Active database, you must have:
|---------------------------------------------------------------------------------------|-------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| name \<CRDB_name\> | string | Name of the Active-Active database (required) |
| memory-size \<maximum_memory\> | size in bytes, megabytes (MB), or gigabytes (GB) | Maximum database memory (required) |
| 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 |
| 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/>• Either a username and password, or certificate credentials:<br/>&nbsp;&nbsp;- `username` and `password` - Cluster username and password<br/>&nbsp;&nbsp;- `client_cert` and `client_key` - Client certificate and its private key, as PEM strings<br/><br/>Don't provide both for the same cluster. The command fails with `Use either username/password or client_cert/client_key/trusted_ca, not both`.<br/><br/>**Optional:**<br/>• `trusted_ca` - CA that validates the API certificate the peer cluster presents, as a PEM string. Only valid with certificate credentials. If you omit it, the cluster uses the certificates in its `mtls_trusted_ca.pem` file.<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<br/><br/>See [Certificate-based authentication for cluster management]({{<relref "/operate/rs/security/certificates/certificate-based-authentication#certificate-based-authentication-for-cluster-management">}}). |
| port \<port_number\> | integer | TCP port for the Active-Active database on all participating clusters |
| default-db-config \<configuration\> | string | Default database configuration options. For a list of database settings, see the [CRDB database config object]({{<relref "/operate/rs/references/rest-api/objects/crdb/database_config">}}) reference.|
| default-db-config-file \<filename\> | filepath | Default database configuration options from a file. For a list of database settings, see the [CRDB database config object]({{<relref "/operate/rs/references/rest-api/objects/crdb/database_config">}}) reference.|
Expand Down Expand Up @@ -117,3 +117,11 @@ To create an Active-Active database with 1 shard in each instance and not wait f
```sh
crdb-cli crdb create --name mycrdb --memory-size 100mb --port 12000 --instance fqdn=cluster1.redis.local,username=admin@redis.local,password=admin --instance fqdn=cluster2.redis.local,username=admin@redis.local,password=admin --no-wait
```

To create an Active-Active database where one participating cluster uses certificate credentials instead of a username and password:

```sh
crdb-cli crdb create --name mycrdb --memory-size 100mb --port 12000 \
--instance fqdn=cluster1.redis.local,username=admin@redis.local,password=admin \
--instance fqdn=cluster2.redis.local,client_cert=<client-cert>,client_key=<client-key>,trusted_ca=<trusted-ca>
```
14 changes: 12 additions & 2 deletions content/operate/rs/references/cli-utilities/crdb-cli/crdb/update.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ crdb-cli crdb update --crdb-guid <guid>
[--default-db-config-file <filename>]
[--compression <0-6>]
[--causal-consistency { true | false } ]
[--credentials id=<id>,username=<username>,password=<password> ]
[--credentials id=<id>,{ username=<username>,password=<password> | client_cert=<cert>,client_key=<key>[,trusted_ca=<ca>] } ]
[--encryption { true | false } ]
[--oss-cluster { true | false } ]
[--featureset-version { true | false } ]
Expand All @@ -42,7 +42,7 @@ If you want to change the configuration of the local instance only, use [`rladmi
| memory-size \<maximum_memory\> | size in bytes, kilobytes (KB), or gigabytes (GB) | Maximum database memory (required) |
| causal-consistency | true <br/>false | [Causal consistency]({{< relref "/operate/rs/databases/active-active/causal-consistency.md" >}}) applies updates to all instances in the order they were received |
| compression | 0-6 | The level of data compression: <br /><br /> 0 = No compression <br /><br /> 6 = High compression and resource load (Default: 3) |
| credentials id=\<id\>,username=\<username\>,password=\<password\> | strings | Updates the credentials for access to the instance |
| credentials id=\<id\>,username=\<username\>,password=\<password\> | strings | Updates the credentials for access to the instance identified by `id`.<br/><br/>Provide either a username and password, or certificate credentials—not both. The command fails with `Use either username/password or client_cert/client_key/trusted_ca, not both`.<br/><br/>• `username` and `password` - Cluster username and password<br/>• `client_cert` and `client_key` - Client certificate and its private key, as PEM strings. Both are required for certificate credentials.<br/>• `trusted_ca` - Optional CA that validates the API certificate the peer cluster presents, as a PEM string. If you omit it, the cluster uses the certificates in its `mtls_trusted_ca.pem` file.<br/><br/>Use this option to migrate a participating cluster from a username and password to certificate credentials. See [Certificate-based authentication for cluster management]({{<relref "/operate/rs/security/certificates/certificate-based-authentication#certificate-based-authentication-for-cluster-management">}}). |
| default-db-config \<configuration\> | | Default database configuration from stdin. For a list of database settings, see the [CRDB database config object]({{<relref "/operate/rs/references/rest-api/objects/crdb/database_config">}}) reference. |
| default-db-config-file \<filename\> | filepath | Default database configuration from file. For a list of database settings, see the [CRDB database config object]({{<relref "/operate/rs/references/rest-api/objects/crdb/database_config">}}) reference.|
| encryption | true <br/>false | Activates or deactivates encryption |
Expand Down Expand Up @@ -79,3 +79,13 @@ Task <task-id> created
---> Status changed: queued -> started
---> Status changed: started -> finished
```

The following example switches a participating cluster from a username and password to certificate credentials:

```sh
$ crdb-cli crdb update --crdb-guid <crdb-guid> \
--credentials id=2,client_cert=<client-cert>,client_key=<client-key>,trusted_ca=<trusted-ca>
Task <task-id> created
---> Status changed: queued -> started
---> Status changed: started -> finished
```
21 changes: 17 additions & 4 deletions content/operate/rs/references/cli-utilities/rladmin/cluster/join.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,8 @@ Adds a node to an existing cluster.
```sh
rladmin cluster join
nodes <node IP address>
username <admin user email>
password <admin password>
{ username <admin user email> password <admin password>
| client_cert <path> client_key <path> [ trusted_ca <path> ] }
[ ephemeral_path <path> ]
[ persistent_path <path> ]
[ ccs_persistent_path <path> ]
Expand All @@ -44,6 +44,8 @@ rladmin cluster join
| accept_servers | 'enabled'<br />'disabled' | Allows allocation of resources on the new node when enabled (optional) |
| addr | IP address | Sets a node's internal IP address. If not provided, the node sets the address automatically. (optional) |
| ccs_persistent_path | filepath (default:&nbsp;/var/opt/redislabs/persist) | Path to the CCS snapshot location (the default is the same as persistent_path) (optional) |
| client_cert | filepath | Path to a file containing the client certificate in PEM format. Use either a username and password or certificate credentials to join a node. Required with `client_key`. See [Certificate-based authentication for cluster management]({{<relref "/operate/rs/security/certificates/certificate-based-authentication#certificate-based-authentication-for-cluster-management">}}). |
| client_key | filepath | Path to a file containing the client certificate's private key in PEM format. Required with `client_cert`. |
| cnm_http_port | integer | Joins a cluster that has a non-default cnm_http_port (optional) |
| ephemeral_path | filepath | Path to the ephemeral storage location (optional) |
| external_addr | list of IP addresses | Sets a node's external IP addresses (space-delimited list). If not provided, the node sets the address automatically. (optional) |
Expand All @@ -52,12 +54,13 @@ rladmin cluster join
| nodes | IP address | Internal IP address of an existing node in the cluster |
| override_rack_id | | Changes to a new rack, specified by `rack_id` (optional) |
| override_repair | | Enables joining a cluster with a dead node (optional) |
| password | string | Admin user's password |
| password | string | Admin user's password. Required unless you use certificate credentials. |
| persistent_path | filepath (default:&nbsp;/var/opt/redislabs/persist) | Path to the persistent storage location (optional) |
| rack_id | string | Moves the node to the specified rack (optional) |
| replace_node | integer | Replaces the specified node with the new node (optional) |
| second_rack_id | string | The unique identifier of the node's second rack ID for two-dimensional rack awareness (optional) |
| username | email address | Admin user's email address |
| trusted_ca | filepath | Path to a file containing the CA that validates the API certificate the cluster presents, in PEM format. If you omit it, the node uses the certificates in the cluster's `mtls_trusted_ca.pem` file. (optional) |

@cursor cursor Bot Aug 6, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Join trusted_ca default wording

Medium Severity

For optional trusted_ca on rladmin cluster join, the new text says the joining node falls back to the cluster's mtls_trusted_ca.pem. Before a successful join, that node is not yet a member of the target cluster, so implying the target cluster’s on-disk trust store is used is inconsistent with how join authentication works.

Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit 5baf3bc. Configure here.

| username | email address | Admin user's email address. Required unless you use certificate credentials. |

### Returns

Expand All @@ -71,3 +74,13 @@ $ rladmin cluster join nodes 192.0.2.2 \
password admin-password
Joining cluster... ok
```

To join a node using certificate credentials instead of a username and password, pass the file paths to the certificate, key, and CA:

```sh
$ rladmin cluster join nodes 192.0.2.2 \
client_cert /etc/opt/redislabs/client.pem \
client_key /etc/opt/redislabs/client.key \
trusted_ca /etc/opt/redislabs/ca.pem
Joining cluster... ok
```
Loading
Loading