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.
gravitational · Apr 5, 2022 · 834a111 · 834a111
1 parent a99d3b4
commit 834a111
Show file tree

Hide file tree

Showing 5 changed files with 157 additions and 46 deletions.
diff --git 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:
 
+<ScopedBlock scope={["oss", "enterprise"]}>
+
 - [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.
+
+</ScopedBlock>
+<ScopedBlock scope={["cloud"]}>
+
+- [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`.
+
+</ScopedBlock>
+
 - [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
@@ -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.
+<Tabs>
+<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">
+
+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).
+
+</TabItem>
+<TabItem scope={["cloud"]} label="Teleport Cloud">
 
-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`|
+
+</TabItem>
+</Tabs>
 
 ## 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).
+For more details please refer to the reference
+[configuration file](./reference/configuration.mdx#database-service-configuration).
diff --git 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
@@ -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.
 
+<ScopedBlock scope={["oss", "enterprise"]}>
+
 ```code
 $ teleport db start \
     --token=/path/to/token \
@@ -18,13 +18,27 @@ $ teleport db start \
     --uri=postgres.example.com:5432
 ```
 
+</ScopedBlock>
+<ScopedBlock scope={["cloud"]}>
+
+```code
+$ teleport db start \
+    --token=/path/to/token \
+    --auth-server=mytenant.teleport.sh:3080 \
+    --name=example \
+    --protocol=postgres \
+    --uri=postgres.mytenant.teleport.sh:5432
+```
+
+</ScopedBlock>
+
 | 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.
 
+<ScopedBlock scope={["oss", "enterprise"]}>
+
 ```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
 ```
 
+</ScopedBlock>
+<ScopedBlock scope={["cloud"]}>
+
+```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
+```
+
+</ScopedBlock>
+
 | 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
@@ -14,6 +14,9 @@ appearing in `teleport.yaml` configuration file:
 
 ## Proxy configuration
 
+<Tabs>
+<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">
+
 The following Proxy service configuration is relevant for Database Access:
 
 <Admonition
@@ -51,6 +54,32 @@ proxy_service:
   mongo_public_addr: "mongo.teleport.example.com:443"
 ```
 
+</TabItem>
+<TabItem scope={["cloud"]} label="Teleport Cloud">
+
+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"
+```
+
+</TabItem>
+</Tabs>
+
 ## Database resource
 
 Full YAML spec of database resources managed by `tctl` resource commands: