title | description |
---|---|
Database Access Getting Started Guide |
Getting started with Teleport Database Access and AWS Aurora PostgreSQL. |
In this getting started guide we will use Teleport Database Access to connect to a PostgreSQL AWS Aurora database.
Here's an overview of what we will do:
- Configure an AWS Aurora database with IAM authentication.
- Join the Aurora database to your Teleport cluster.
- Connect to the Aurora database via the Teleport Database Service.
<ScopedBlock scope={["oss", "enterprise"]}> <ScopedBlock scope={["cloud"]}>
Teleport Database Access is available starting from the 6.0.0
Teleport
release.
(!docs/pages/includes/edition-prereqs-tabs.mdx!)
- An AWS account with a PostgreSQL AWS Aurora database 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!)
In order to allow Teleport connections to an Aurora instance, the instance needs to support IAM authentication.
If you don't have a database provisioned yet, create an instance of an Aurora PostgreSQL in the RDS control panel. Make sure to choose the "Standard create" database creation method and enable "Password and IAM database authentication" in the Database Authentication dialog.
For existing Aurora instances, the status of IAM authentication is displayed on the Configuration tab and can be enabled by modifying the database instance.
Next, create the following IAM policy and attach it to the AWS user or service account. The Teleport Database Service will need to use the credentials of this AWS user or service account in order to use this policy.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"rds-db:connect"
],
"Resource": [
"arn:aws:rds-db:<region>:<account-id>:dbuser:<resource-id>/*"
]
}
]
}
This policy allows any database account to connect to the Aurora instance specified with resource ID using IAM auth.
<Admonition type="note" title="Resource ID"
The database resource ID is shown on the Configuration tab of a particular
database instance in the RDS control panel, under "Resource id". For regular
RDS database it starts with db-
prefix. For Aurora, use the database
cluster resource ID (cluster-
), not the individual instance ID.
Finally, connect to the database and create a database account with IAM auth support (or update an existing one). Once connected, execute the following SQL statements to create a new database account and allow IAM auth for it:
CREATE USER alice;
GRANT rds_iam TO alice;
For more information about connecting to the PostgreSQL instance directly, see the AWS documentation.
(!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!)
<ScopedBlock scope={["oss", "enterprise"]}>
On the node where you will run the Teleport Database Service, start Teleport and
point it to your Aurora database instance. Make sure to update the database
endpoint and region appropriately. The --auth-server
flag must point to the
address of your Teleport Proxy Service.
$ teleport db start \
--token=/tmp/token \
--name=aurora \
--auth-server=teleport.example.com:3080 \
--protocol=postgres \
--uri=postgres-aurora-instance-1.abcdefghijklm.us-west-1.rds.amazonaws.com:5432 \
--aws-region=us-west-1
On the node where you will run the Teleport Database Service, start Teleport and
point it to your Aurora database instance. Make sure to update the database
endpoint and region appropriately. The --auth-server
flag must point to the
address of your Teleport Cloud tenant.
$ teleport db start \
--token=/tmp/token \
--name=aurora \
--auth-server=mytenant.teleport.sh:443 \
--protocol=postgres \
--uri=postgres-aurora-instance-1.abcdefghijklm.us-west-1.rds.amazonaws.com:5432 \
--aws-region=us-west-1
<Admonition type="note" title="AWS Credentials"
The node that connects to the database should have AWS credentials configured with the policy from step 1.
Create the role that will allow a user to connect to any database using any database account:
$ tctl create <<EOF
kind: role
version: v3
metadata:
name: db
spec:
allow:
db_labels:
'*': '*'
db_names:
- '*'
db_users:
- '*'
EOF
Create the Teleport user assigned the db
role we've just created:
$ tctl users add --roles=access,db alice
Now that Aurora is configured with IAM authentication, Teleport is running, and the local user is created, we're ready to connect to the database.
Log in to Teleport with the user we've just created.
<ScopedBlock scope={["oss", "enterprise"]}>
$ tsh login --proxy=teleport.example.com --user=alice
$ tsh login --proxy=mytenant.teleport.sh --user=alice
Now we can inspect available databases:
$ tsh db ls
Finally, connect to the database:
$ tsh db connect --db-user=alice --db-name postgres aurora
(!docs/pages/includes/database-access/aws-troubleshooting.mdx!)
For the next steps, dive deeper into the topics relevant to your Database Access use-case, for example:
- Check out configuration guides.
- Learn how to configure GUI clients.
- Learn about Database Access role-based access control.
- See frequently asked questions.