Use the CockroachDB CLI to provision a development cluster

On this page Carat arrow pointing down
Warning:
As of November 24, 2023, CockroachDB v22.1 is no longer supported. For more details, refer to the Release Support Policy.

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.

Note:

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

  1. Create two directories:

    icon/buttons/copy
    $ mkdir certs
    
    icon/buttons/copy
    $ 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.
  2. Generate the CA certificate and key:

    icon/buttons/copy
    $ cockroach cert create-ca \
    --certs-dir=certs \
    --ca-key=my-safe-directory/ca.key
    
    icon/buttons/copy
    $ 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

  1. Generate the certificate and key for the first node:

    icon/buttons/copy
    $ 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
    
    icon/buttons/copy
    $ 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
    
  2. Upload certificates to the first node:

    icon/buttons/copy
    # Create the certs directory:
    $ ssh <username>@<node1 address> "mkdir certs"
    
    icon/buttons/copy
    # Upload the CA certificate and node certificate and key:
    $ scp certs/ca.crt \
    certs/node.crt \
    certs/node.key \
    <username>@<node1 address>:~/certs
    
  3. Delete the local copy of the first node's certificate and key:

    icon/buttons/copy
    $ rm certs/node.crt certs/node.key
    
    Note:
    This is necessary because the certificates and keys for additional nodes will also be named node.crt and node.key As an alternative to deleting these files, you can run the next cockroach cert create-node commands with the --overwrite flag.
  4. Create the certificate and key for the second node:

    icon/buttons/copy
    $ cockroach cert create-node \
    node2.example.com \
    node2.another-example.com \
    --certs-dir=certs \
    --ca-key=my-safe-directory/ca.key
    
    icon/buttons/copy
    $ 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
    
  5. Upload certificates to the second node:

    icon/buttons/copy
    # Create the certs directory:
    $ ssh <username>@<node2 address> "mkdir certs"
    
    icon/buttons/copy
    # Upload the CA certificate and node certificate and key:
    $ scp certs/ca.crt \
    certs/node.crt \
    certs/node.key \
    <username>@<node2 address>:~/certs
    
  6. 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.

icon/buttons/copy
$ cockroach cert create-client \
maxroach \
--certs-dir=certs \
--ca-key=my-safe-directory/ca.key
icon/buttons/copy
$ 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.

icon/buttons/copy
$ 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)

See also


Yes No
On this page

Yes No