To secure your CockroachDB cluster's inter-node and client-node communication, the cluster requires a certificate authority (CA) certificate that is used to sign keys and certificates (SSLs) for:
- Nodes
- Clients
- Optionally: the DB Console.
With Auto TLS, your cluster creates the CA (certificate authority) certificate and key pair required for secure communication with other nodes and clients and then securely distributes these among the nodes. The cluster also creates the additional certificates that each node requires to connect to other nodes and enable connections from clients.
This feature is an alpha release with core functionality that may not yet meet your requirements. Planned enhancements in future versions include:
- Auto TLS cert generation when adding more nodes to an existing cluster, though cert generation for such nodes is already possible using
cockroach certon clusters that initially used Auto TLS. Note that relevant example steps in Start a Local Cluster show a folder name for storing the CA key that may differ from what you have used with Auto TLS, so these may need to be adapted. - Support for cross-region deployments (cases where not all nodes are on the same subnet, and the listening and advertised addresses are different).
- Identification of misconfigurations leading to helpful error messages, while suppressing unnecessary warnings.
- Additional CLI instructions and feedback.
Auto TLS simplifies the default method for creating secure clusters. Rather than manually generating certificates and keys and distributing them to all nodes, you run a one-time cockroach connect command for each node, specifying a common token. A CA cert and key are distributed to all nodes, along with all other certificates that nodes require to communicate with other nodes and with clients, all signed by the CA.
To create client certificates, you will still need to run cockroach cert create-client or the equivalent OpenSSL commands and manually distribute these.
Step 1: Configure nodes
The example commands below must be tailored for your environment and run for each node. In a production environment, this would typically require running the commands once on each machine for the single node that each one hosts. However, these examples depict multiple nodes running on a single machine, varying their ports rather than their hosts.
For each node, prepare a directory for the node to use to store the generated certificates and keys.
cd node1 mkdir certsAlternatively, the directory
~/.cockroach-certsis used, by default, if none is specified in the next step.For each node, run
cockroach connect. Specify a shared token, certs directory, number of nodes you'll have when starting the cluster, and the address and port on which the node will listen for connections from the others (which defaults tolocalhost:26257).For example, for the first node:
cockroach connect \ --listen-addr=localhost:26257 \ --num-expected-initial-nodes 3 \ --certs-dir=certs \ --init-token={secret}The interface responds that it is
waiting for handshake from 2 peers. Thecockroach connectprocess remains active until the specified number of nodes are in communication and the cert distribution is complete.Prepare each additional node, specifying the addresses of those to
joinwhich are awaiting the handshake.cockroach connect \ --listen-addr=localhost:26258 \ --num-expected-initial-nodes 3 \ --join=localhost:26257 \ --certs-dir=certs \ --init-token={secret}cockroach connect \ --listen-addr=localhost:26259 \ --num-expected-initial-nodes 3 \ --join=localhost:26257,localhost:26258 \ --certs-dir=certs \ --init-token={secret}Each node displays feedback as it connects to each peer. For example, the first would report:
waiting for handshake for 2 peers trusted peer: 127.0.0.1:26258 trusted peer: 127.0.0.1:26259When the handshakes are successful among all expected nodes, one is automatically selected to generate the certificates and distribute them. It reports that it is
generatingandsendinga cert bundle to its peers, while the others report that they arewaitingfor and thenreceivingthe cert bundle.Finally, all nodes report
server certificate generation complete. Thecerts-dirdirectory on each is populated with all required files.Run
cockroach startfor each node. This starts the node, but does not yet initialize the cluster. If testing this process on a single machine, run the following in each node's directory, adjusting the port numbers for each.
cockroach start \
--listen-addr=localhost:26257 \
--certs-dir=certs \
--join=localhost:26258,localhost:26259
--http-addr=localhost:8080
Step 2: Create a client certificate for the root user
On any node's machine, manually create the certificate and key pair for the root user.
Do not share the root cert. In a later step, you can use the root user to create additional administrative users, specifying their privileges. You can then create and securely share their certs, as appropriate, using the principle of least privilege.
cockroach cert create-client root \
--ca-key=certs/ca.key --certs-dir=certs
Step 3: Initialize the cluster
Run cockroach-init.
cockroach init --certs-dir=certs --host=localhost:26257
Step 4: Create additional users to administer the cluster
Using the
rootuser, log in to the SQL shell. Create additional users, specifying role options as parameters, or add the users as members of theadminrole to confer all role options, if appropriate.Create the certificate and key pair for each of the additional users.
cockroach cert create-client {username} \ --ca-key=certs/ca.key --certs-dir=certsSecurely send each user the certificate and key that matches their username:
client.{username}.crtandclient.{username}.key.
See also
cockroach certcockroach auth-session- Authenticate to CockroachDB Self-Hosted Clusters
- GSSAPI Authentication
- SQL Authentication
- Cloud Storage Authentication
Was this helpful?
