From 834a111c5ddacc82eabcfaefb3746198bda5c9bf Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Thu, 31 Mar 2022 14:54:31 -0400 Subject: [PATCH] Add Cloud instructions to five guides Backports #11516 * Add Cloud instructions to five guides See #10637 Database Access FAQ - Add tabbed instructions where answers differ for Cloud/Self-Hosted - Style/grammar tweaks Dynamic Registration - While this guide is edition agnostic, I have added the tctl.mdx partial so Cloud users know to log in to Teleport before running tctl commands. Configuration reference - The only part that required different instructions for Cloud users was the reference configuration for the Proxy Service. I have supplied the values hardcoded in Teleport Cloud. CLI reference - Add ScopedBlocks where examples mention proxy.example.com--use a Cloud tenant address for Cloud readers. - Light style/grammar edits Architecture - This guide is mostly edition agnostic. After the overview diagram, I used a ScopedBlock to make it clear to Cloud users that the Proxy Service uses the Teleport Cloud tenant address. * Respond to PR feedback Also remove mongo_public_addr from the Cloud proxy_service config, since this was included incorrectly. --- docs/pages/database-access/architecture.mdx | 17 ++- docs/pages/database-access/faq.mdx | 109 ++++++++++++------ .../guides/dynamic-registration.mdx | 2 + docs/pages/database-access/reference/cli.mdx | 46 ++++++-- .../reference/configuration.mdx | 29 +++++ 5 files changed, 157 insertions(+), 46 deletions(-) diff --git a/docs/pages/database-access/architecture.mdx b/docs/pages/database-access/architecture.mdx index dc31f83dd85f7..73cf58425a388 100644 --- a/docs/pages/database-access/architecture.mdx +++ b/docs/pages/database-access/architecture.mdx @@ -3,8 +3,6 @@ title: Database Access Architecture description: How Teleport Database Access works. --- -# Database Access Architecture - This section provides an overview of Teleport Database Access inner workings. ## How it works @@ -15,9 +13,22 @@ Let's take a look at a sample Database Access deployment: In it, we have the following Teleport components: + + - [Teleport Proxy](../architecture/proxy.mdx). A stateless service - that performs a function of an authentication gateway, serves web UI and + that performs a function of an authentication gateway, serves the Web UI, and accepts database (and other) client connections. + + + + +- [Teleport Proxy](../architecture/proxy.mdx). A stateless service that performs + a function of an authentication gateway, serves the Web UI, and accepts + database (and other) client connections. This service is accessible at your + Teleport Cloud tenant URL, e.g., `mytenant.teleport.sh`. + + + - [Teleport Auth](../architecture/authentication.mdx). Serves as cluster's certificate authority, handles user authentication/authorization and issues short-lived client certificates. diff --git a/docs/pages/database-access/faq.mdx b/docs/pages/database-access/faq.mdx index 43542fe2a4051..a579246b8c7ed 100644 --- a/docs/pages/database-access/faq.mdx +++ b/docs/pages/database-access/faq.mdx @@ -3,76 +3,113 @@ title: Database Access FAQ description: Frequently asked questions about Teleport Database Access. --- -# Database Access FAQ - ## Which database protocols does Teleport Database Access support? -Teleport Database Access currently supports PostgreSQL, MySQL, MariaDB and MongoDB -protocols. +Teleport Database Access currently supports the following protocols: + +- MariaDB +- Microsoft SQL Server +- MongoDB +- MySQL +- PostgreSQL +- Redis + +For PostgreSQL and MySQL, the following Cloud-hosted versions are supported in addition to self-hosted deployments: + +- Amazon RDS +- Amazon Aurora (except for Amazon Aurora Serverless, which doesn't support IAM authentication) +- Amazon Redshift +- Google Cloud SQL +- Azure Database -For PostgreSQL and MySQL, both self-hosted and cloud-hosted versions such as AWS -RDS, Aurora (except for Serverless version which doesn't support IAM auth), -Redshift, and GCP Cloud SQL are supported. See available [guides](./guides.mdx) -for all supported configurations. +See the available [guides](./guides.mdx) for all supported configurations. ## Which PostgreSQL protocol features are not supported? The following PostgreSQL protocol features aren't currently supported: - [Canceling requests in progress](https://www.postgresql.org/docs/current/protocol-flow.html#id-1.10.5.7.9). - Cancel requests issued by the PostgreSQL clients connected to Teleport proxy - won't be passed to the database server. -- Any of the [authentication methods](https://www.postgresql.org/docs/current/auth-methods.html) + Cancel requests issued by the PostgreSQL clients connected to the Teleport + Proxy Service won't be passed to the database server. +- Any [authentication methods](https://www.postgresql.org/docs/current/auth-methods.html) except for client certificate authentication and IAM authentication for cloud databases. -## Can database clients use public address different from web public address? +## Can database clients use a public address different from the web public address? -Teleport administrators can set `postgres_public_addr` and `mysql_public_addr` -proxy configuration fields to public addresses over which respective database -clients should connect. See [Proxy Configuration](./reference/configuration.mdx#proxy-configuration) -for more details. + + + +When configuring the Teleport Proxy Service, administrators can set the +`postgres_public_addr` and `mysql_public_addr` configuration fields to public +addresses over which respective database clients should connect. See +[Proxy Configuration](./reference/configuration.mdx#proxy-configuration) for +more details. + +This is useful when the Teleport Web UI is running behind an L7 load balancer +(e.g. ALB in AWS), in which case the PostgreSQL/MySQL proxy needs to be exposed +on a plain TCP load balancer (e.g. NLB in AWS). + + + -This is useful when Teleport web proxy UI is running behind an L7 load balancer -(e.g. ALB in AWS) in which case PostgreSQL/MySQL proxy need to be exposed on a -plain TCP load balancer (e.g. NLB in AWS). +In Teleport Cloud, the Proxy Service uses the following ports for +Database Access client traffic: + +|Configuration setting|Port| +|---|---| +|`mysql_public_addr`|`3036`| +|`postgres_public_addr`|`443`| +|`mongo_public_addr`|`443`| + + + ## Do you support X database client? -Teleport relies on client certificates for authentication so any database client -that supports this method of authentication and uses modern TLS (1.2+) should -work. +Teleport relies on client certificates for authentication, so any database +client that supports this method of authentication and uses modern TLS (1.2+) +should work. -Standard command-line clients such as `psql`, `mysql`, `mongo` or `mongosh` are supported, -there are also instructions for configuring select [graphical clients](./guides/gui-clients.mdx). +Standard command-line clients such as `psql`, `mysql`, `mongo` or `mongosh` are +supported. There are also instructions for configuring select +[graphical clients](./guides/gui-clients.mdx). ## When will you support X database? We plan to support more databases in the future based on customer demand. See if the database you're interested in has already been requested among -[Github issues](https://github.com/gravitational/teleport/labels/database-access) +[GitHub issues](https://github.com/gravitational/teleport/labels/database-access) or open a [new issue](https://github.com/gravitational/teleport/issues/new/choose) to register your interest. ## Can I provide a custom CA certificate? -Yes, you can pass custom CA certificate by using +Yes, you can pass custom CA certificate by using a [configuration file](./reference/configuration.mdx#database-service-configuration) (look at `ca_cert_file`). ## Can I provide a custom DNS name for Teleport generated CA? -Yes, use `server_name` under `tls` section in configuration file. Please look on our -reference [configuration file](./reference/configuration.mdx#database-service-configuration) +Yes, use `server_name` under the `tls` section in your Teleport configuration +file. Please look on our reference +[configuration file](./reference/configuration.mdx#database-service-configuration) for more details. -## Can I disable CA verification when connecting to database? +## Can I disable CA verification when connecting to a database? + +Yes, although it is not recommended. Certificate verification prevents +person-in-the-middle attacks and makes sure that you +are connected to the database that you intended to. + +Teleport also allows you to edit your +[configuration file](./reference/configuration.mdx#database-service-configuration) +to provide a custom CA certificate (`ca_cert_file`) or custom DNS name +(`server_name`), which is more secure. + +If none of the above options work for you and you still want to disable the CA +check, you can use `mode` under the `tls` option in the Teleport configuration file. -Yes, although is not recommended. Certificate verification prevents from man in the middle attack -and makes sure that you are connected to the database that you intended to. Teleport also allows to -provide a [custom CA certificate](#can-i-provide-a-custom-ca-certificate) or -[custom DNS name](#can-i-provide-a-custom-dns-name-for-teleport-generated-ca) which is more secure. -If none of the above options don't work for you and you still want to disable the CA check -you can use `mode` under `tls` option in the Teleport configuration file. For more details please refer -to the reference [configuration file](./reference/configuration.mdx#database-service-configuration). \ No newline at end of file +For more details please refer to the reference +[configuration file](./reference/configuration.mdx#database-service-configuration). \ No newline at end of file diff --git a/docs/pages/database-access/guides/dynamic-registration.mdx b/docs/pages/database-access/guides/dynamic-registration.mdx index ff1bbaa4099e4..d666286da40ee 100644 --- a/docs/pages/database-access/guides/dynamic-registration.mdx +++ b/docs/pages/database-access/guides/dynamic-registration.mdx @@ -66,6 +66,8 @@ To create a database resource, run: $ tctl create database.yaml ``` +(!docs/pages/includes/tctl.mdx!) + After the resource has been created, it will appear among the list of available databases (in `tsh db ls` or UI) as long as at least one database agent picks it up according to its label selectors. diff --git a/docs/pages/database-access/reference/cli.mdx b/docs/pages/database-access/reference/cli.mdx index d66839001b05a..af026e5b14c52 100644 --- a/docs/pages/database-access/reference/cli.mdx +++ b/docs/pages/database-access/reference/cli.mdx @@ -3,12 +3,12 @@ title: Database Access CLI Reference description: CLI reference for Teleport Database Access. --- -# Database Access CLI Reference - ## teleport db start Starts Teleport Database Service agent. + + ```code $ teleport db start \ --token=/path/to/token \ @@ -18,13 +18,27 @@ $ teleport db start \ --uri=postgres.example.com:5432 ``` + + + +```code +$ teleport db start \ + --token=/path/to/token \ + --auth-server=mytenant.teleport.sh:3080 \ + --name=example \ + --protocol=postgres \ + --uri=postgres.mytenant.teleport.sh:5432 +``` + + + | Flag | Description | | - | - | | `-d/--debug` | Enable verbose logging to stderr. | | `--pid-file` | Full path to the PID file. By default no PID file will be created. | -| `--auth-server` | Address of the Teleport proxy server. | -| `--token` | Invitation token to register with an auth server. | -| `--ca-pin` | CA pin to validate the auth server. | +| `--auth-server` | Address of the Teleport Proxy Service. | +| `--token` | Invitation token to register with the Auth Service. | +| `--ca-pin` | CA pin to validate the Auth Service. | | `-c/--config` | Path to a configuration file (default `/etc/teleport.yaml`). | | `--labels` | Comma-separated list of labels for this node, for example `env=dev,app=web`. | | `--fips` | Start Teleport in FedRAMP/FIPS 140-2 mode. | @@ -42,6 +56,8 @@ $ teleport db start \ Creates a sample Database Service configuration. + + ```code $ teleport db configure create --rds-discovery=us-west-1 --rds-discovery=us-west-2 $ teleport db configure create \ @@ -53,6 +69,22 @@ $ teleport db configure create \ --labels=env=prod ``` + + + +```code +$ teleport db configure create --rds-discovery=us-west-1 --rds-discovery=us-west-2 +$ teleport db configure create \ + --token=/tmp/token \ + --proxy=mytenant.teleport.sh:3080 \ + --name=example \ + --protocol=postgres \ + --uri=postgres://postgres.mytenant.teleport.sh:5432 \ + --labels=env=prod +``` + + + | Flag | Description | | - | - | | `--proxy` | Teleport Proxy Service address to connect to. Default: `0.0.0.0:3080`. | @@ -61,7 +93,7 @@ $ teleport db configure create \ | `--redshift-discovery` | List of AWS regions the agent will discover for Redshift instances. | | `--ca-pin` | CA pin to validate the Auth Service (can be repeated for multiple pins). | | `--name` | Name of the proxied database. | -| `--protocol` | Proxied database protocol. Supported are: [postgres mysql mongodb cockroachdb redis sqlserver]. | +| `--protocol` | Proxied database protocol. Supported are: `[postgres mysql mongodb cockroachdb redis sqlserver]`. | | `--uri` | Address the proxied database is reachable at. | | `--labels` | Comma-separated list of labels for the database, for example env=dev,dept=it | | `-o/--output` | Write to stdout with `-o=stdout`, the default config file with `-o=file`, or a custom path with `-o=file:///path` | @@ -80,7 +112,7 @@ $ teleport db configure bootstrap -c /etc/teleport.yaml --manual | - | - | | `-c/--config` | Path to a configuration file. Default: `/etc/teleport.yaml`. | | `--manual` | When executed in "manual" mode, this command will print the instructions to complete the configuration instead of applying them directly. | -| `--policy-name` | Name of the Teleport Database Service policy. Default: "DatabaseAccess" | +| `--policy-name` | Name of the Teleport Database Service policy. Default: `DatabaseAccess` | | `--confirm` | Do not prompt the user and auto-confirm all actions. | | `--attach-to-role` | Role name to attach the policy to. Mutually exclusive with `--attach-to-user`. If none of the attach-to flags is provided, the command will try to attach the policy to the current user/role based on the credentials. | | `--attach-to-user` | User name to attach the policy to. Mutually exclusive with `--attach-to-role`. If none of the attach-to flags is provided, the command will try to attach the policy to the current user/role based on the credentials. | diff --git a/docs/pages/database-access/reference/configuration.mdx b/docs/pages/database-access/reference/configuration.mdx index df6aad3c23a1a..8107f6adae1f4 100644 --- a/docs/pages/database-access/reference/configuration.mdx +++ b/docs/pages/database-access/reference/configuration.mdx @@ -14,6 +14,9 @@ appearing in `teleport.yaml` configuration file: ## Proxy configuration + + + The following Proxy service configuration is relevant for Database Access: + + +Teleport Cloud automatically configures the Teleport Proxy Service with the +following settings that are relevant to Database Access. This reference +configuration uses `mytenant.teleport.sh` in place of your Teleport Cloud tenant +address. + +```yaml +proxy_service: + enabled: "yes" + # PostgreSQL proxy is listening on the regular web proxy port. + web_listen_addr: "0.0.0.0:3080" + # MySQL proxy is listening on a separate port. + mysql_listen_addr: "0.0.0.0:3036" + # Database clients will connect to the Proxy Service over this hostname. + public_addr: "mytenant.teleport.sh:443" + # Address advertised to MySQL clients. + mysql_public_addr: "mytenant.teleport.sh:3036" + # Address advertised to PostgreSQL clients. + postgres_public_addr: "mytenant.teleport.sh:443" +``` + + + + ## Database resource Full YAML spec of database resources managed by `tctl` resource commands: