The CockroachDB CLI's cockroach cert
command allows you to generate private key/public certificate pairs for TLS authentication and encryption in communication between CockroachDB nodes, and from SQL clients to the cluster.
The ability to rapidly and locally generate private key/public certificate pairs is important for development, but careful management of security certificates is an essential component of cluster security. We recommend that you use a cloud-native tool, such as Google Cloud Platform's Certificate Authority Service (CAS), to manage security certificates.
Learn more: Manage PKI certificates for a CockroachDB deployment with HashiCorp Vault.
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. Keep the key safe and secret; do 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 \ *.dev.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
To create a certificate and a key pair for a client, use the create-client
subcommand.
$ 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
To list the certificates and keys in a directory, use the create-client
subcommand.
$ 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)