docs: cockroachdb storage backend configuration (#37880)

* docs: cockroachdb storage backend configuration * fix missing code block end quotes * Update docs/pages/reference/backends.mdx Co-authored-by: Zac Bergquist <[email protected]> * Update crdb deploy and config references * Update docs/pages/reference/backends.mdx Co-authored-by: Paul Gottschling <[email protected]> * Update docs/pages/reference/backends.mdx Co-authored-by: Paul Gottschling <[email protected]> * Update docs/pages/reference/backends.mdx Co-authored-by: Paul Gottschling <[email protected]> * Fix auth server lint * Fix spellcheck lint * Update docs/pages/reference/backends.mdx Co-authored-by: Zac Bergquist <[email protected]> * Update docs/pages/reference/backends.mdx Co-authored-by: Zac Bergquist <[email protected]> --------- Co-authored-by: Zac Bergquist <[email protected]> Co-authored-by: Paul Gottschling <[email protected]> Co-authored-by: Alexander Klizhentas <[email protected]>
gravitational · Mar 10, 2024 · 13ceef6 · 13ceef6
1 parent e148c72
commit 13ceef6
Show file tree

Hide file tree

Showing 2 changed files with 89 additions and 0 deletions.
diff --git a/docs/cspell.json b/docs/cspell.json
@@ -126,6 +126,7 @@
     "Mailgun",
     "Minidriver",
     "Moba",
+    "MODIFYCLUSTERSETTING",
     "Mqgcq",
     "Multifactor",
     "Multihost",
@@ -161,6 +162,7 @@
     "Println",
     "Quickstart",
     "Quicktime's",
+    "rangefeed",
     "REDISCLI",
     "REPLCONF",
     "REPLICAOF",

diff --git a/docs/pages/reference/backends.mdx b/docs/pages/reference/backends.mdx
@@ -1429,3 +1429,90 @@ the location set the `data_dir` value within the Teleport configuration file.
 teleport:
   data_dir: /var/lib/teleport_data
 ```
+
+## CockroachDB
+
+Teleport can use [CockroachDB](https://www.cockroachlabs.com/) as a storage backend
+to achieve high availability and survive regional failures. You must take steps to 
+protect access to CockroachDB in this configuration because that is where Teleport
+secrets like keys and user records will be stored.
+
+<Admonition
+  type="warning"
+  title="IMPORTANT"
+>
+  CockroachDB can currently only be used to store Teleport's cluster state.
+  It cannot be used for Teleport's audit log in the same way that
+  [DynamoDB](#dynamodb) or [Firestore](#firestore) can.
+</Admonition>
+
+At a minimum you must configure CockroachDB to allow Teleport to create tables.
+Teleport will create the database if given permission to do so but this is not
+required if the database already exists.
+
+```
+CREATE DATABASE database_name;
+CREATE USER database_user;
+GRANT CREATE ON DATABASE database_name TO database_user;
+```
+
+You must also enable change feeds in CockroachDB's cluster settings. Teleport
+will configure this setting itself if granted `SYSTEM MODIFYCLUSTERSETTING`.
+
+```
+SET CLUSTER SETTING kv.rangefeed.enabled = true;
+```
+
+There are several ways to deploy and configure CockroachDB,
+the details of which are not in scope for this guide. To learn about deploying
+CockroachDB, see [CockroachDB's deployment options](https://www.cockroachlabs.com/docs/stable/choose-a-deployment-option).
+To learn about how to configure multi-region survival goals, see
+[multi-region survival goals](https://www.cockroachlabs.com/docs/stable/multiregion-survival-goals).
+
+To configure Teleport to use CockroachDB as a storage backend:
+- Configure all Teleport Auth Service instances to use the CockroachDB backend in the
+  `storage` section of `teleport.yaml` as shown below.
+- Deploy several Auth Service instances connected to the CockroachDB storage backend.
+- Deploy several Proxy Service instances.
+- Make sure that the Proxy Service instances and all Teleport agent services that
+  connect directly to the the Auth Service have the `auth_server` configuration
+  setting populated with the address of a load balancer for Auth Service
+  instances.
+
+```yaml
+teleport:
+  storage:
+    type: cockroachdb
+
+    # conn_string is a required parameter. It is a PostgreSQL connection string used
+    # to connect to CockroachDB using the PostgreSQL wire protocol. Client
+    # parameters may be specified using the URL. For a detailed list of available
+    # parameters see https://www.cockroachlabs.com/docs/stable/connection-parameter
+    #
+    # If your certificates are not stored at the default ~/.postgresql
+    # location, you will need to specify them with the sslcert, sslkey, and
+    # sslrootcert parameters.
+    #
+    # pool_max_conns is an additional parameter that determines the maximum
+    # number of connections in the connection pool used for the cluster state
+    # database (the change feed uses an additional connection), defaulting to
+    # a value that depends on the number of available CPUs.
+    conn_string: postgresql://user_name@database-address/teleport_backend?sslmode=verify-full&pool_max_conns=20
+
+    # change_feed_conn_string is an optional parameter. When unspecified Teleport
+    # will default to using the same value specified for conn_string. It may be used
+    # to configure Teleport to use a different user or connection parameters when
+    # establishing a change feed connection.
+    #
+    # If your certificates are not stored at the default ~/.postgresql
+    # location, you will need to specify them with the sslcert, sslkey, and
+    # sslrootcert parameters.
+    change_feed_conn_string: postgresql://user_name@database-address/teleport_backend?sslmode=verify-full
+
+    # ttl_job_cron is an optional parameter which configures the interval at which CockroachDB will expire backend
+    # items based on their time to live. By default this is configured to run every
+    # 20 minutes. This is used by Teleport to clean up old resources that are no longer
+    # connected to or needed by Teleport. Note that configuring this to run more
+    # frequently may have performance implications for CockroachDB.
+    ttl_job_cron: '*/20 * * * *'
+```