Skip to content

Latest commit

 

History

History
226 lines (170 loc) · 6.27 KB

getting-started.mdx

File metadata and controls

226 lines (170 loc) · 6.27 KB
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:

  1. Configure an AWS Aurora database with IAM authentication.
  2. Join the Aurora database to your Teleport cluster.
  3. Connect to the Aurora database via the Teleport Database Service.

<ScopedBlock scope={["oss", "enterprise"]}> Teleport Database Access RDS Self-Hosted <ScopedBlock scope={["cloud"]}> Teleport Database Access RDS Cloud

Prerequisites

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!)

Step 1/4. Set up Aurora

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.

Step 2/4. Start the Teleport Database Service

(!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.

Step 3/4. Create a user and role

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

Step 4/4. Connect

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

Troubleshooting

(!docs/pages/includes/database-access/aws-troubleshooting.mdx!)

Next Steps

For the next steps, dive deeper into the topics relevant to your Database Access use-case, for example: