backport #37606 to branch/v14.

docs/pages/database-access/guides/cockroachdb-self-hosted.mdx

@@ -20,17 +20,16 @@ description: How to configure Teleport database access with self-hosted Cockroac
 (!docs/pages/includes/edition-prereqs-tabs.mdx!)
 
 - CockroachDB cluster.
+
 - A host, e.g., an Amazon EC2 instance, where you will run the Teleport Database
   Service.
+
 - (!docs/pages/includes/tctl.mdx!)
+
 - A certificate authority to issue CockroachDB certificates for nodes in your 
   CockroachDB cluster.
-  Teleport uses a split CA architecture for database access, and requires that
-  you create your own CA for node-to-node mTLS communication.
-  See [cockroach cert](https://www.cockroachlabs.com/docs/stable/cockroach-cert)
-  for instructions on creating a CA and issuing a client certificate and key
-  for each node. The certificate and key should be named `client.node.crt` and 
-  `client.node.key`.
+
+  (!docs/pages/includes/database-access/split-db-ca-details.mdx db="CockroachDB"!)
 
 ## Step 1/4. Set up the Teleport Database Service
 
@@ -81,49 +80,128 @@ in the CockroachDB documentation for more information.
 
 ### Set up mutual TLS
 
-(!docs/pages/includes/database-access/tctl-auth-sign.mdx!)
-
 To set up mutual TLS authentication, you need to make sure that:
 
 - Teleport trusts certificates presented by CockroachDB nodes.
-- CockroachDB trusts client certificates signed by Teleport.
+- CockroachDB nodes trust client certificates signed by both your CockroachDB CA
+  and your Teleport cluster's `db_client` CA.
+
+CockroachDB nodes need to trust the Teleport `db_client` CA so that Teleport 
+users can authenticate to your CockroachDB cluster as clients.
+
+The CockroachDB CA needs to be trusted by each CockroachDB node so that nodes 
+can authenticate themselves as clients to other nodes in the CockroachDB 
+cluster. This is because CockroachDB uses mTLS for node-to-node communication.
+
+<Tabs>
+<TabItem label="Nodes serving your CockroachDB CA certs">
+In this configuration, your CockroachDB CA will be used to issue the server cert
+`node.crt` for each CockroachDB node. 
 
-Generate the secrets by running the following `tctl` command against your
-Teleport cluster:
+This configuration is simpler to set up, because an existing CockroachDB cluster 
+already has `node.crt` issued for each node and you only need to configure the 
+CockroachDB nodes to trust your Teleport `db_client` CA.
+Another benefit is that your CockroachDB nodes will continue to serve the same
+CockroachDB CA-issued cert, rather than serving a new cert signed by Teleport's
+`db` CA, so you don't have to configure other clients to trust a new CA.
+
+Copy your CockroachDB CA cert to `ca-client.crt` in the certs directory of
+each CockroachDB node:
+
+```code
+$ CERTS_DIR=<Var name="/path/to/cockroachdb/certs/dir" />
+$ cp "${CERTS_DIR}/ca.crt" "${CERTS_DIR}/ca-client.crt"
+```
+
+Next, for each CockroachDB node, export Teleport's `db_client` CA using `tctl` 
+(or export it once and copy it to each node) and append the certificate to 
+`ca-client.crt`:
+
+```code
+$ tctl auth export --type=db_client >> <Var name="/path/to/cockroachdb/certs/dir" />/ca-client.crt
+```
+
+(!docs/pages/includes/database-access/custom-db-ca.mdx db="CockroachDB" protocol="cockroachdb" port="26257"!)
+</TabItem>
+<TabItem label="Nodes serving your Teleport CA certs">
+In this configuration, Teleport's CA will be used to issue the server cert, 
+`node.crt`, and your own custom CA will be used to issue the client certificate,
+`client.node.crt`, for each CockroachDB node.
+
+(!docs/pages/includes/database-access/tctl-auth-sign.mdx!)
+
+Generate secrets for a CockroachDB node using `tctl`:
 
 ```code
 $ tctl auth sign \
     --format=cockroachdb \
     --host=roach.example.com \
-    --out=/path/to/cockroach/certs/dir/ \
+    --out=<Var name="/path/to/cockroachdb/certs/dir" /> \
     --ttl=2190h
 ```
 
+(!docs/pages/includes/database-access/ttl-note.mdx!)
+
 The command will produce 4 files:
 - `ca.crt` with Teleport's `db` certificate authority
 - `ca-client.crt` with Teleport's `db_client` certificate authority
 - `node.crt` / `node.key` with the node's certificate and key.
 
+<Admonition type="note">
+You can specify multiple comma-separated addresses e.g. 
+`--host=roach,node-1,192.168.1.1`.
+However, you must include the hostname that Teleport will use to connect to the
+database.
+</Admonition>
+
 Do not rename these files as this is how CockroachDB expects them to be named.
 See [Node key and certificates](https://www.cockroachlabs.com/docs/v21.1/create-security-certificates-custom-ca#node-key-and-certificates)
 for details.
 
-Generate the secrets for each cluster node and make sure to use the hostname
-Teleport will be using to connect to the nodes in the `--host` flag.
+Prepend your CockroachDB CA's certificate to `ca-client.crt`.
+Now issue a client certificate for the node using your CockroachDB CA:
 
-<Admonition type="tip">
-  You can specify multiple comma-separated addresses e.g. `--host=roach,node-1,192.168.1.1`.
-</Admonition>
+```code
+$ cockroach cert create-client node \
+  --certs-dir=<Var name="/path/to/cockroachdb/certs/dir" /> \
+  --ca-key=ca-secrets/ca-client.key
+```
+
+<Details title="Seeing an error message about TLS key mismatch?">
+If you see an error message like: `tls: private key does not match public key`,
+it likely means you did not prepend your CockroachDB CA cert to `ca-client.crt`
+earlier.
+
+`cockroach cert create-client` expects the first certificate in `ca-client.crt`
+(in the `--certs-dir` specified) to be the certificate signed by `--ca-key`.
+Ensure that your CockroachDB CA certificate is the first certificate in
+`ca-client.crt`.
+</Details>
+
+Now copy `<Var name="/path/to/cockroachdb/certs/dir" />` to the CockroachDB
+node and repeat these steps for all of your other CockroachDB nodes.
+</TabItem>
+</Tabs>
 
 Restart your CockroachDB nodes, passing them the directory with generated secrets
 via the `--certs-dir` flag:
 
 ```code
 $ cockroach start \
-    --certs-dir=/path/to/cockroachdb/certs/dir/ \
+    --certs-dir=<Var name="/path/to/cockroachdb/certs/dir" /> \
     # other flags...
 ```
 
+Alternatively, if the nodes were already started with 
+`--certs-dir=<Var name="/path/to/cockroachdb/certs/dir" />`, you can send a
+`SIGHUP` signal to the `cockroach` process to reload certificates without 
+restarting the node. You must send `SIGHUP` as the same user that started the
+`cockroach` process:
+
+```code
+$ pkill -SIGHUP -x cockroach
+```
+
 ## Step 4/4. Connect
 
 Log in to your Teleport cluster. Your CockroachDB cluster should appear in the

docs/pages/database-access/guides/mongodb-self-hosted.mdx

@@ -22,27 +22,18 @@ videoBanner: 6lgVObxoLkc
 
 - MongoDB cluster (standalone or replica set) version `(=mongodb.min_version=)` or newer.
 
-<Admonition type="note">
+  <Admonition type="note">
   Teleport database access supports MongoDB `(=mongodb.min_version=)` and newer.
   Older versions have not been tested and are not guaranteed to work. MongoDB
   `(=mongodb.min_version=)` was released in November 2017 and reached EOL in
   April 2021 so if you're still using an older version, consider upgrading.
-</Admonition>
+  </Admonition>
 
 - (!docs/pages/includes/tctl.mdx!)
 - A certificate authority for MongoDB Replica Set, and the public certificate
-  for that CA, in PEM format, e.g. `/path/to/your/ca.crt`.
+  for that CA, in PEM format: `<Var name="/path/to/your/ca.crt" />`.
 
-  <Admonition type="note">
-  A MongoDB replica set requires that each MongoDB server is configured with a 
-  certificate that has extendedKeyUsage `clientAuth, serverAuth`.
-
-  Teleport uses a split CA architecture for better security:
-  the Teleport Database Server CA issues certs with `serverAuth`
-  and the Teleport Database Client CA issues certs with `clientAuth`.
-  Therefore, you must provide each MongoDB server with a certificate issued by
-  your own CA with extendedKeyUsage `clientAuth, serverAuth`.
-  </Admonition>
+  (!docs/pages/includes/database-access/split-db-ca-details.mdx db="MongoDB Replica Set"!)
 
 ## Step 1/3. Install and configure Teleport
 
@@ -124,12 +115,10 @@ accordingly to grant the user appropriate database permissions.
 
 ### Set up mutual TLS
 
-(!docs/pages/includes/database-access/tctl-auth-sign.mdx!)
-
-Create the secrets:
-
 <Tabs>
   <TabItem label="Standalone">
+  (!docs/pages/includes/database-access/tctl-auth-sign.mdx!)
+
   When connecting to standalone MongoDB, sign the certificate for the hostname over
   which Teleport will be connecting to it.
 
@@ -152,28 +141,14 @@ Create the secrets:
 
   ```code
   $ tctl auth export --type=db_client > db-client-ca.crt
-  $ cat /path/to/your/ca.crt db-client-ca.crt > /etc/certs/mongo.cas
+  $ cat <Var name="/path/to/your/ca.crt" /> db-client-ca.crt > /etc/certs/mongo.cas
   ```
 
   When MongoDB is configured to trust these CAs, it will trust the Teleport 
   Database Client CA and allow access via Teleport, while still allowing MongoDB 
   replication over TLS using your CA's certs for peer verification.
 
-  Next, modify your Teleport Database Service to trust your MongoDB Replica 
-  Set CA:
-  ```yaml
-    databases:
-    - name: "example-mongo"
-      protocol: "mongodb"
-      uri: "mongo.example.com:27017"
-      static_labels:
-        "env": "dev"
-      tls:
-        ca_cert_file: "/path/to/your/ca.crt"
-  ```
-  
-  Now the Teleport Database Service will trust certificates presented by your
-  MongoDB Replica Set.
+    (!docs/pages/includes/database-access/custom-db-ca.mdx db="MongoDB Replica Set" protocol="mongodb" port="27017"!)
   </TabItem>
 </Tabs>