Database access docs overhaul

docs/config.json

@@ -10,6 +10,7 @@
         { "title": "User Manual", "slug": "/user-manual/" },
         { "title": "Application Guide", "slug": "/application-access/" },
         { "title": "Kubernetes Guide", "slug": "/kubernetes-access/" },
+        { "title": "Database Access", "slug": "/database-access/" },
         { "title": "Admin Manual", "slug": "/admin-guide/" },
         { "title": "Production Guide", "slug": "/production/" },
         { "title": "FAQ", "slug": "/faq/" },
@@ -21,7 +22,6 @@
       "title": "Preview",
       "entries": [
         { "title": "Upcoming Releases", "slug": "/preview/upcoming-releases/" },
-        { "title": "Database Access", "slug": "/preview/database-access/" },
         { "title": "Cloud", "slug": "/preview/cloud/" }
       ]
     },
@@ -35,6 +35,28 @@
         { "title": "OpenSSH Guide", "slug": "/openssh-teleport/" }
       ]
     },
+    {
+      "icon": "database",
+      "title": "Database Access",
+      "entries": [
+        { "title": "Getting Started", "slug": "/database-access/getting-started/" },
+        {
+          "title": "Guides",
+          "slug": "/database-access/guides/",
+          "entries": [
+            { "title": "PostgreSQL on AWS", "slug": "/database-access/guides/postgres-aws" },
+            { "title": "MySQL on AWS", "slug": "/database-access/guides/mysql-aws" },
+            { "title": "Self-Hosted PostgreSQL", "slug": "/database-access/guides/postgres-self-hosted/" },
+            { "title": "Self-Hosted MySQL", "slug": "/database-access/guides/mysql-self-hosted/" },
+            { "title": "Database GUI Clients", "slug": "/database-access/guides/gui-clients/" }
+          ]
+        },
+        { "title": "RBAC", "slug": "/database-access/rbac/" },
+        { "title": "Architecture", "slug": "/database-access/architecture/" },
+        { "title": "Reference", "slug": "/database-access/reference/" },
+        { "title": "FAQ", "slug": "/database-access/faq/" }
+      ]
+    },
     {
       "icon": "building",
       "title": "Teleport Enterprise",

docs/pages/database-access.mdx

@@ -0,0 +1,56 @@
+---
+title: Database Access
+description: Teleport Database Access introduction, demo and resources
+---
+
+# Database Access
+
+Teleport can provide secure access to PostgreSQL and MySQL databases, while
+improving both access control and visibility.
+
+Some of the things you can do with Database Access:
+
+* Users can retrieve short-lived database certificates using single sign-on
+  flow thus maintaining their organization-wide identity.
+* Configure role-based access controls for databases and implement custom
+  [access workflows](./enterprise/workflow/index.mdx).
+* Capture database access events as well as query activity in the audit log.
+
+## Demo
+
+Let's connect to a PostgreSQL server with `psql` and pgAdmin 4 after authenticating
+with Github, execute a few SQL queries and observe them in the audit log:
+
+<video autoPlay loop muted playsInline controls>
+  <source src="https://goteleport.com/teleport/videos/database-access-preview/dbaccessdemo.mp4" type="video/mp4" />
+  <source src="https://goteleport.com/teleport/videos/database-access-preview/dbaccessdemo.webm" type="video/webm" />
+Your browser does not support the video tag.
+</video>
+
+## Getting Started
+
+Configure Database Access in a 10 minute [Getting Started](./database-access/getting-started.mdx)
+guide.
+
+## Guides
+
+* [AWS RDS/Aurora PostgreSQL](./database-access/guides/postgres-aws.mdx)
+* [AWS RDS/Aurora MySQL](./database-access/guides/mysql-aws.mdx)
+* [Self-hosted PostgreSQL](./database-access/guides/postgres-self-hosted.mdx)
+* [Self-hosted MySQL](./database-access/guides/mysql-self-hosted.mdx)
+* [GUI clients](./database-access/guides/gui-clients.mdx)
+
+## Resources
+
+To learn more about configuring role-based access control for Database Access,
+check out [RBAC](./database-access/rbac.mdx) section.
+
+[Architecture](./database-access/architecture.mdx) provides a more in-depth
+look at Database Access internals such as networking and security.
+
+See [Reference](./database-access/reference.mdx) for an overview of
+Database Access related configuration and CLI commands.
+
+## FAQ
+
+Finally, check out [Frequently Asked Questions](./database-access/faq.mdx).

docs/pages/database-access/architecture.mdx

@@ -0,0 +1,132 @@
+---
+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
+
+Let's take a look at a sample Database Access deployment:
+
+![Teleport Database Access Diagram](../../img/database-access/diagram.png)
+
+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
+  accepts database (and other) client connections.
+* [Teleport Auth](../architecture/authentication.mdx). Serves as
+  cluster's certificate authority, handles user authentication/authorization
+  and issues short-lived client certificates.
+* Teleport Database Service. The Database Access' "brain" that connects
+  to the databases, performs database authentication and protocol parsing.
+
+Database Service establishes an SSH reverse tunnel to the Proxy. As such, users
+do not need to have direct connectivity to the Database Service, or the databases
+it's connected to. As long as it can dial back to the cluster's Proxy server, it
+can be located behind a firewall.
+
+<Admonition type="tip" title="Tip">
+You can have multiple Database Services connected to the cluster. Each
+Database Service can be also connected to multiple databases.
+</Admonition>
+
+Let's take a look at the typical flow Database Access users go through to
+connect to a database.
+
+1. A user logs into the cluster with `tsh login` command and retrieves
+   a client certificate. See [Issuing User Certificates](../architecture/authentication.mdx#issuing-user-certificates)
+   for more details on how it works.
+2. The user picks the database they want to connect to from the list of available
+   databases shown in `tsh db ls` command and retrieves a short-lived X.509
+   certificate for it with `tsh db login`.
+3. The user uses a standard database client (e.g. `psql`, `mysql` or one of the
+   [graphical clients](./guides/gui-clients.mdx)) to connect to the Proxy, authenticating
+   with the client certificate from step 2.
+4. The Proxy authenticates the connection and dispatches it to the appropriate
+   Database Service based on the routing information encoded in the client
+   certificate, over the reverse tunnel.
+5. The Database Service authenticates the connection, performs an authorization
+   check, and then establishes the connection to the database.
+6. The Database Service begins proxying traffic between the user's database
+   client and the database. Additionally, it interprets the database wire
+   protocol messages and submits events to the Teleport audit log.
+
+## Authentication
+
+Teleport relies on short-lived X.509 certificates for user authentication, as
+well as authentication between internal components.
+
+Authentication happens in 3 places:
+
+* Database client connecting to Proxy
+* Proxy connecting to Database Service
+* Database Service connecting database.
+
+Let's take a detailed look at each authentication point.
+
+### Database Client to Proxy
+
+Database clients authenticate with the Proxy using X.509 client certificates
+obtained from the `tsh db login` command.
+
+<Admonition type="note" title="SSL">
+Many database clients/servers refer to these certificates as SSL which is
+legacy terminology. In Teleport documentation we most often refer to them as
+TLS or x509 certificates.
+</Admonition>
+
+The login command updates database-specific local configuration files (e.g.
+PostgreSQL [connection service file](https://www.postgresql.org/docs/13/libpq-pgservice.html)
+or MySQL [option file](https://dev.mysql.com/doc/refman/8.0/en/option-files.html)
+to group connection information for a particular database, which CLI clients
+can refer to.
+
+For configuring graphical clients, there is a `tsh db config` command that
+prints detailed information about the connection such as host/port and location
+of the secrets. See [GUI Clients](./gui-clients.mdx) for details.
+
+### Proxy to Database Service
+
+The connection between the Proxy and the Database Service is also authenticated
+with mutual TLS.
+
+The Proxy generates a short-lived X.509 certificate signed by the
+cluster's host authority, with the client's identity and database routing
+information encoded in it, and uses it to authenticate with the Database Service.
+
+### Database Service to Database
+
+Database authentication is handled differently for self-hosted databases and
+databases hosted by AWS.
+
+#### Self-Hosted
+
+Teleport Database Service uses client certificate authentication with self-hosted
+database servers.
+
+See respective configuration guides for [PostgreSQL](./guides/postgres-self-hosted.mdx)
+and [MySQL](./guides/mysql-self-hosted.mdx) for details on configuring client certificate
+authentication.
+
+#### AWS RDS / Aurora
+
+With RDS and Aurora database instances, the Database Service authenticates using
+[IAM Authentication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html).
+
+The Database Service automatically generates an IAM token for each connection
+and uses the token as a password.
+
+See respective configuration guides for [PostgreSQL](./guides/postgres-aws.mdx) and
+[MySQL](./guides/mysql-aws.mdx) for details on configuring IAM authentication.
+
+## Next Steps
+
+Please refer to the [RFD #11](https://github.com/gravitational/teleport/blob/024fd582e62560ffc925cd4b4d42c156043c041b/rfd/0011-database-access.md)
+for a more in-depth description of the feature scope and design.
+
+See [Architecture Overview](../architecture/overview.mdx) for general Teleport
+architecture principles.

docs/pages/database-access/faq.mdx

@@ -0,0 +1,40 @@
+---
+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 and MySQL protocols.
+
+## 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)
+  except for client certificate authentication and IAM authentication for AWS
+  RDS and Aurora databases.
+
+## 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.
+
+Standard command-line clients such as `psql` and `mysql` are supported, there
+are also instructions for configuring select [graphical clients](./guides/gui-clients.mdx).
+
+## When will you support X database?
+
+We're focusing on PostgreSQL and MySQL initially but planning to support more
+databases in the future based on the 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)
+or open a [new issue](https://github.com/gravitational/teleport/issues/new/choose)
+to register your interest.