A secure CockroachDB cluster uses TLS for encrypted inter-node and client-node communication, which requires CA, node, and client certificates and keys. To create these certificates and keys, use the cockroach cert
commands with the appropriate subcommands and flags, or use openssl
commands.
How Security Certificates Work
Using the
cockroach cert
command, you create a CA certificate and key and then node and client certificates that are signed by the CA certificate. Since you need access to a copy of the CA certificate and key to create node and client certs, it's best to create everything in one place.You then upload the appropriate node certificate and key and the CA certificate to each node, and you upload the appropriate client certificate and key and the CA certificate to each client.
When nodes establish contact to each other, and when clients establish contact to nodes, they use the CA certificate to verify each other's identity.
Subcommands
Subcommand | Usage |
---|---|
create-ca |
Create the self-signed certificate authority (CA), which you'll use to create and authenticate certificates for your entire cluster. |
create-node |
Create a certificate and key for a specific node in the cluster. You specify all addresses at which the node can be reached and pass appropriate flags. |
create-client |
Create a certificate and key for a specific user accessing the cluster from a client. You specify the username of the user who will use the certificate and pass appropriate flags. |
list |
List certificates and keys found in the certificate directory. |
Certificate Directory
When using cockroach cert
to create node and client certificates, you will need access to a local copy of the CA certificate and key. It is therefore recommended to create all certificates and keys in one place and then distribute node and client certificates and keys appropriately. For the CA key, be sure to store it somewhere safe and keep a backup; if you lose it, you will not be able to add new nodes or clients to your cluster. For a walkthrough of this process, see Manual Deployment.
The create-*
subcommands generate the CA certificate and all node and client certificates and keys in a single directory specified by the --certs-dir
flag, with the files named as follows:
File name pattern | File usage |
---|---|
ca.crt |
CA certificate |
node.crt |
Server certificate |
node.key |
Key for server certificate |
client.<user>.crt |
Client certificate for <user> (eg: client.root.crt for user root ) |
client.<user>.key |
Key for the client certificate |
Note the following:
The CA key is never loaded automatically by
cockroach
commands, so it should be created in a separate directory, identified by the--ca-key
flag.Keys (files ending in
.key
) must not have group or world permissions (maximum permissions are 0700, orrwx------
). This check can be disabled by setting the environment variableCOCKROACH_SKIP_KEY_PERMISSION_CHECK=true
.
Synopsis
# Create the CA certificate and key:
$ cockroach cert create-ca \
--certs-dir=[path-to-certs-directory] \
--ca-key=[path-to-ca-key]
# Create a node certificate and key:
$ cockroach cert create-node \
[node-hostname] \
[node-other-hostname] \
[node-yet-another-hostname] \
--certs-dir=[path-to-certs-directory] \
--ca-key=[path-to-ca-key]
# Create a client certificate and key:
$ cockroach cert create-client \
[username] \
--certs-dir=[path-to-certs-directory] \
--ca-key=[path-to-ca-key]
# List certificates and keys:
$ cockroach cert list \
--certs-dir=[path-to-certs-directory]
# View help:
$ cockroach cert --help
$ cockroach cert create-ca --help
$ cockroach cert create-node --help
$ cockroach cert create-client --help
$ cockroach cert list --help
Flags
The cert
command and subcommands support the following general-use and logging flags.
General
Flag | Description |
---|---|
--certs-dir |
The path to the certificate directory containing all certificates and keys needed by cockroach commands.This flag is used by all subcommands. Default: ${HOME}/.cockroach-certs/ |
--ca-key |
The path to the private key protecting the CA certificate. This flag is required for all create-* subcommands. When used with create-ca in particular, it defines where to create the CA key; the specified directory must exist.Env Variable: COCKROACH_CA_KEY |
--allow-ca-key-reuse |
When running the create-ca subcommand, pass this flag to re-use an existing CA key identified by --ca-key . Otherwise, a new CA key will be generated.This flag is used only by the create-ca subcommand. It helps avoid accidentally re-using an existing CA key. |
--overwrite |
When running create-* subcommands, pass this flag to allow existing files in the certificate directory (--certs-dir ) to be overwritten.This flag helps avoid accidentally overwriting sensitive certificates and keys. |
--lifetime |
The lifetime of the certificate, in hours, minutes, and seconds. Certificates are valid from the time they are created through the duration specified in --lifetime .Default: 87840h0m0s (10 years) |
--key-size |
The size of the CA, node, or client key, in bits. Default: 2048 |
Logging
By default, the cert
command logs errors to stderr
.
If you need to troubleshoot this command's behavior, you can change its logging behavior.
Examples
Create the CA certificate and key pair
Create two directories:
$ mkdir certs
$ mkdir my-safe-directory
certs
: You'll generate your CA certificate and all node and client certificates and keys in this directory and then upload some of the files to your nodes.my-safe-directory
: You'll generate your CA key in this directory and then reference the key when generating node and client certificates. After that, you'll keep the key safe and secret; you will not upload it to your nodes.
Generate the CA certificate and key:
$ cockroach cert create-ca \ --certs-dir=certs \ --ca-key=my-safe-directory/ca.key
$ ls -l certs
total 8 -rw-r--r-- 1 maxroach maxroach 1.1K Jul 10 14:12 ca.crt
Create the certificate and key pairs for nodes
Generate the certificate and key for the first node:
$ cockroach cert create-node \ node1.example.com \ node1.another-example.com \ --certs-dir=certs \ --ca-key=my-safe-directory/ca.key
$ ls -l certs
total 24 -rw-r--r-- 1 maxroach maxroach 1.1K Jul 10 14:12 ca.crt -rw-r--r-- 1 maxroach maxroach 1.2K Jul 10 14:16 node.crt -rw------- 1 maxroach maxroach 1.6K Jul 10 14:16 node.key
Upload certificates to the first node:
# Create the certs directory: $ ssh <username>@<node1 address> "mkdir certs"
# Upload the CA certificate and node certificate and key: $ scp certs/ca.crt \ certs/node.crt \ certs/node.key \ <username>@<node1 address>:~/certs
Delete the local copy of the first node's certificate and key:
$ rm certs/node.crt certs/node.key
Note:This is necessary because the certificates and keys for additional nodes will also be namednode.crt
andnode.key
As an alternative to deleting these files, you can run the nextcockroach cert create-node
commands with the--overwrite
flag.Create the certificate and key for the second node:
$ cockroach cert create-node \ node2.example.com \ node2.another-example.com \ --certs-dir=certs \ --ca-key=my-safe-directory/ca.key
$ ls -l certs
total 24 -rw-r--r-- 1 maxroach maxroach 1.1K Jul 10 14:12 ca.crt -rw-r--r-- 1 maxroach maxroach 1.2K Jul 10 14:17 node.crt -rw------- 1 maxroach maxroach 1.6K Jul 10 14:17 node.key
Upload certificates to the second node:
# Create the certs directory: $ ssh <username>@<node2 address> "mkdir certs"
# Upload the CA certificate and node certificate and key: $ scp certs/ca.crt \ certs/node.crt \ certs/node.key \ <username>@<node2 address>:~/certs
Repeat steps 3 - 5 for each additional node.
Create the certificate and key pair for a client
$ cockroach cert create-client \
maxroach \
--certs-dir=certs \
--ca-key=my-safe-directory/ca.key
$ ls -l certs
total 40
-rw-r--r-- 1 maxroach maxroach 1.1K Jul 10 14:12 ca.crt
-rw-r--r-- 1 maxroach maxroach 1.1K Jul 10 14:13 client.maxroach.crt
-rw------- 1 maxroach maxroach 1.6K Jul 10 14:13 client.maxroach.key
-rw-r--r-- 1 maxroach maxroach 1.2K Jul 10 14:17 node.crt
-rw------- 1 maxroach maxroach 1.6K Jul 10 14:17 node.key
List certificates and keys
$ cockroach cert list \
--certs-dir=certs
Certificate directory: certs
+-----------------------+---------------------+---------------------+------------+--------------------------------------------------------+-------+
| Usage | Certificate File | Key File | Expires | Notes | Error |
+-----------------------+---------------------+---------------------+------------+--------------------------------------------------------+-------+
| Certificate Authority | ca.crt | | 2027/07/18 | num certs: 1 | |
| Node | node.crt | node.key | 2022/07/14 | addresses: node2.example.com,node2.another-example.com | |
| Client | client.maxroach.crt | client.maxroach.key | 2022/07/14 | user: maxroach | |
+-----------------------+---------------------+---------------------+------------+--------------------------------------------------------+-------+
(3 rows)