diff --git a/docs/cspell.json b/docs/cspell.json index 6cece1b2a9a..373493a7e19 100644 --- 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 index aba2abca1a8..25a573d8107 100644 --- 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. + + + 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. + + +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 * * * *' +``` \ No newline at end of file