mirror of
https://github.com/gravitational/teleport.git
synced 2026-11-02 06:08:23 +08:00
Paul Gottschling
95df3ec2ae
* Add more info re: AWS credentials to the docs Closes #2781 - Add a partial for how to provide credentials to Teleport's AWS client. Since this includes adding environment variables to the file used by our systemd service, I also created a partial re: how to configure Teleport's systemd service and added these two partials to the relevant guides. - Removed `Admonition`s that link to the docs re: AWS credentials in favor of the partial above. (The partial links to the Go SDK for AWS docs for situations where users have a specific use case.) - Remove mentions of the AWS credential-related config settings from the Backends reference. The example config snippets don't actually include the `access_key` and `secret_key` settings, so these are left over from an earlier version of the guide. While you can still add these settings to a config file, I thought it would make sense to leave them undocumented since using an EC2 instance, environment variables, etc. is the recommended approach. - Split the S3/DynamoDB sections of the Backends reference into subsections so the extra authentication info fits a bit better. * Respond to PR feedback * Add new partials to the RDS Proxy guide
215 lines
6.7 KiB
Plaintext
215 lines
6.7 KiB
Plaintext
---
|
|
title: Database Access with AWS RDS and Aurora
|
|
h1: Database Access with AWS RDS and Aurora for PostgreSQL, MySQL and MariaDB
|
|
description: How to configure Teleport Database Access with AWS RDS and Aurora for PostgreSQL, MySQL and MariaDB.
|
|
---
|
|
|
|
This guide will help you to:
|
|
|
|
- Install Teleport `(=teleport.version=)`.
|
|
- Set up Teleport to access your RDS instances and Aurora clusters.
|
|
- Connect to your databases through Teleport.
|
|
|
|
<ScopedBlock scope={["oss", "enterprise"]}>
|
|
|
|
</ScopedBlock>
|
|
<ScopedBlock scope={["cloud"]}>
|
|
|
|
</ScopedBlock>
|
|
|
|
<Admonition type="note" title="Supported versions">
|
|
The following products are not compatible with Database Access as they don't support IAM authentication:
|
|
- Aurora Serverless v1.
|
|
- RDS MariaDB versions lower than 10.6.
|
|
|
|
It is recommended to upgrade Aurora Serverless v1 to
|
|
[Aurora Serverless v2](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-serverless-v2.html)
|
|
which does support IAM authentication.
|
|
</Admonition>
|
|
|
|
## Prerequisites
|
|
|
|
(!docs/pages/includes/edition-prereqs-tabs.mdx!)
|
|
|
|
- AWS account with RDS and Aurora databases and permissions to create and attach
|
|
IAM policies.
|
|
- A host, e.g., an EC2 instance, where you will run the Teleport Database
|
|
Service.
|
|
|
|
(!docs/pages/includes/tctl.mdx!)
|
|
|
|
## Step 1/6. Create a Teleport user
|
|
|
|
(!docs/pages/includes/database-access/create-user.mdx!)
|
|
|
|
## Step 2/6. Create a Database Service configuration
|
|
|
|
(!docs/pages/includes/database-access/token.mdx!)
|
|
|
|
Install Teleport on the host where you will run the Teleport Database Service:
|
|
|
|
(!docs/pages/includes/install-linux.mdx!)
|
|
|
|
Create the Database Service configuration:
|
|
|
|
<ScopedBlock scope={["oss", "enterprise"]}>
|
|
|
|
```code
|
|
$ teleport db configure create \
|
|
-o file \
|
|
--proxy=teleport.example.com:3080 \
|
|
--token=/tmp/token \
|
|
--rds-discovery=us-west-1
|
|
```
|
|
|
|
</ScopedBlock>
|
|
<ScopedBlock scope={["cloud"]}>
|
|
|
|
```code
|
|
$ teleport db configure create \
|
|
-o file \
|
|
--proxy=mytenant.teleport.sh:443 \
|
|
--token=/tmp/token \
|
|
--rds-discovery=us-west-1
|
|
```
|
|
|
|
</ScopedBlock>
|
|
|
|
The command will generate a Database Service configuration with RDS/Aurora
|
|
database auto-discovery enabled on the `us-west-1` region and place it at the
|
|
`/etc/teleport.yaml` location.
|
|
|
|
## Step 3/6. Create an IAM policy for Teleport
|
|
|
|
Teleport needs AWS IAM permissions to be able to:
|
|
|
|
- Discover and register RDS instances and Aurora clusters.
|
|
- Configure IAM authentication for them.
|
|
|
|
Before you can generate IAM permissions, you must provide the Teleport Database
|
|
Service access to AWS credentials.
|
|
|
|
(!docs/pages/includes/aws-credentials.mdx service="the Database Service"!)
|
|
|
|
(!docs/pages/includes/database-access/aws-bootstrap.mdx!)
|
|
|
|
## Step 4/6. Start the Database Service
|
|
|
|
(!docs/pages/includes/start-teleport.mdx service="the Database Service"!)
|
|
|
|
The Database Service will discover all RDS instances and Aurora clusters according to the
|
|
configuration and register them in the cluster. In addition to the primary
|
|
endpoints of the discovered Aurora clusters, their reader and custom endpoints
|
|
will also be registered.
|
|
|
|
The Database Service will also attempt to enable IAM auth and configure IAM access
|
|
policies for the discovered databases. Keep in mind that AWS IAM changes may
|
|
not propagate immediately and can take a few minutes to come into effect.
|
|
|
|
## Step 5/6. Create a database IAM user
|
|
|
|
Database users must allow IAM authentication in order to be used with Database
|
|
Access for RDS. See below how to enable it for your database engine.
|
|
|
|
<Tabs>
|
|
<TabItem label="PostgreSQL">
|
|
PostgreSQL users must have a `rds_iam` role:
|
|
|
|
```sql
|
|
CREATE USER alice;
|
|
GRANT rds_iam TO alice;
|
|
```
|
|
</TabItem>
|
|
<TabItem label="MySQL/MariaDB">
|
|
MySQL and MariaDB users must have the RDS authentication plugin enabled:
|
|
|
|
```sql
|
|
CREATE USER alice IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';
|
|
```
|
|
|
|
Created user may not have access to anything by default so let's grant it
|
|
some permissions:
|
|
|
|
```sql
|
|
GRANT ALL ON `%`.* TO 'alice'@'%';
|
|
```
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
See [Creating a database account using IAM authentication](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/UsingWithRDS.IAMDBAuth.DBAccounts.html)
|
|
for more information.
|
|
|
|
## Step 6/6. Connect
|
|
|
|
Once the Database Service has started and joined the cluster, log in to see the
|
|
registered databases:
|
|
|
|
<ScopedBlock scope={["oss", "enterprise"]}>
|
|
|
|
```code
|
|
$ tsh login --proxy=teleport.example.com --user=alice
|
|
$ tsh db ls
|
|
# Name Description Labels
|
|
# ------------------------------ --------------------------------------------- --------
|
|
# postgres-rds RDS instance in us-west-1 ...
|
|
# aurora-mysql Aurora cluster in us-west-1 ...
|
|
# aurora-mysql-custom-myendpoint Aurora cluster in us-west-1 (custom endpoint) ...
|
|
# aurora-mysql-reader Aurora cluster in us-west-1 (reader endpoint) ...
|
|
```
|
|
|
|
</ScopedBlock>
|
|
<ScopedBlock scope={["cloud"]}>
|
|
|
|
```code
|
|
$ tsh login --proxy=mytenant.teleport.sh --user=alice
|
|
$ tsh db ls
|
|
# Name Description Labels
|
|
# ------------------------------ --------------------------------------------- --------
|
|
# postgres-rds RDS instance in us-west-1 ...
|
|
# aurora-mysql Aurora cluster in us-west-1 ...
|
|
# aurora-mysql-custom-myendpoint Aurora cluster in us-west-1 (custom endpoint) ...
|
|
# aurora-mysql-reader Aurora cluster in us-west-1 (reader endpoint) ...
|
|
```
|
|
|
|
</ScopedBlock>
|
|
|
|
<Admonition type="note" title="Note">
|
|
Primary, reader, and custom endpoints of Aurora clusters have names of
|
|
`<cluster-id>`, `<cluster-id>-reader`, and
|
|
`<cluster-id>-custom-<endpoint-name>` respectively.
|
|
|
|
You can override the `<cluster-id>` part of the name with `teleport.dev/database_name` AWS tag.
|
|
</Admonition>
|
|
|
|
To retrieve credentials for a database and connect to it:
|
|
|
|
```code
|
|
$ tsh db connect postgres-rds
|
|
```
|
|
|
|
You can optionally specify the database name and the user to use by default
|
|
when connecting to the database instance:
|
|
|
|
```code
|
|
$ tsh db connect --db-user=postgres --db-name=postgres postgres-rds
|
|
```
|
|
|
|
<Admonition type="note" title="Note">
|
|
The appropriate database command-line client (`psql`, `mysql`, `mariadb`) should be
|
|
available in `PATH` in order to be able to connect.
|
|
</Admonition>
|
|
|
|
To log out of the database and remove credentials:
|
|
|
|
```code
|
|
$ tsh db logout postgres-rds
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
(!docs/pages/includes/database-access/aws-troubleshooting.mdx!)
|
|
|
|
## Next steps
|
|
|
|
(!docs/pages/includes/database-access/guides-next-steps.mdx!)
|