Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[v9] Edit Database Access guides for Cloud users #11846

Merged
merged 1 commit into from
Apr 11, 2022
Merged

[v9] Edit Database Access guides for Cloud users #11846

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 74 additions & 35 deletions docs/pages/database-access/getting-started.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,33 +3,49 @@ title: Database Access Getting Started Guide
description: Getting started with Teleport Database Access and AWS Aurora PostgreSQL.
---

# Getting Started

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 AWS Aurora database with IAM authentication.
2. Download and install Teleport (=teleport.version=) and connect it to the Aurora database.
3. Connect to the Aurora database via Teleport.
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.

## Prerequisites

<Admonition type="note" title="Supported versions">

Teleport Database Access is available starting from the `6.0.0` Teleport
release.

</Admonition>

- 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/user-client-prereqs.mdx!)

(!docs/pages/includes/tctl.mdx!)

## Step 1/3. Set up Aurora

In order to allow Teleport connections to an Aurora instance, it needs to support
IAM authentication.
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](https://console.aws.amazon.com/rds/home).
Make sure to choose "Standard create" database creation method and enable
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. Teleport Database Service will need to use credentials of this AWS user
or service account in order to use this policy.
account. The Teleport Database Service will need to use the credentials of this
AWS user or service account in order to use this policy.

```json
{
Expand All @@ -55,10 +71,10 @@ with resource ID using IAM auth.
type="note"
title="Resource ID"
>
Database resource ID is shown on the Configuration tab of a particular
database instance in RDS control panel, under "Resource id". For regular
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 individual instance ID.
cluster resource ID (`cluster-`), not the individual instance ID.
</Admonition>

Finally, connect to the database and create a database account with IAM auth
Expand All @@ -71,43 +87,56 @@ GRANT rds_iam TO alice;
```

For more information about connecting to the PostgreSQL instance directly,
see Amazon [documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ConnectToPostgreSQLInstance.html).
see the AWS [documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ConnectToPostgreSQLInstance.html).

## Step 2/3. Set up Teleport

Teleport Database Access is available starting from `6.0.0` release.
### Start the Auth Service and Proxy Service

Download the appropriate version of Teleport for your platform from
our [downloads page](https://goteleport.com/teleport/download).
(!docs/pages/includes/database-access/start-auth-proxy.mdx!)

### Start the Teleport Database Service

### Configure TLS
(!docs/pages/includes/database-access/token.mdx!)

Teleport requires a valid TLS certificate to operate and can fetch one automatically
using Let's Encrypt.

(!docs/pages/includes/acme.mdx!)
<ScopedBlock scope={["oss", "enterprise"]}>

We will assume that you have configured a DNS record for `teleport.example.com` to point to the node where you're launching Teleport.
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.

<Details title="Using Application Access?">
(!docs/pages/includes/dns-app-access.mdx!)
</Details>
```code
$ teleport db start \
--token=/tmp/token \
--db-name=aurora \
--auth-server=teleport.example.com:3080 \
--db-protocol=postgres \
--db-uri=postgres-aurora-instance-1.abcdefghijklm.us-west-1.rds.amazonaws.com:5432 \
--db-aws-region=us-west-1
```

### Start Teleport
</ScopedBlock>
<ScopedBlock scope={["cloud"]}>

Now start Teleport and point it to your Aurora database instance. Make sure to
update the database endpoint and region appropriately.
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.

```code
$ sudo teleport start --config=/tmp/teleport.yaml \
--roles=proxy,auth,db \
$ teleport db start \
--token=/tmp/token \
--db-name=aurora \
--auth-server=mytenant.teleport.sh \
--db-protocol=postgres \
--db-uri=postgres-aurora-instance-1.abcdefghijklm.us-west-1.rds.amazonaws.com:5432 \
--db-aws-region=us-west-1
```

</ScopedBlock>

<Admonition
type="note"
title="AWS Credentials"
Expand Down Expand Up @@ -146,16 +175,26 @@ $ tctl users add --roles=access,db alice

## Step 3/3. Connect

Now that Aurora is configured with IAM authentication, Teleport is running and
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 into Teleport with the user we've just created. Make sure to use `tsh`
version `6.0` or newer that includes Database Access support.
Log in to Teleport with the user we've just created.

<ScopedBlock scope={["oss", "enterprise"]}>

```code
$ tsh login --proxy=teleport.example.com --user=alice
```

</ScopedBlock>
<ScopedBlock scope={["cloud"]}>

```code
$ tsh login --proxy=mytenant.teleport.sh --user=alice
```

</ScopedBlock>

Now we can inspect available databases and retrieve credentials for the
configured Aurora instance:

Expand All @@ -164,8 +203,8 @@ $ tsh db ls
$ tsh db login aurora
```

Finally, connect to the database using `psql` command shown in the output of
`tsh db login` command, which looks similar to this:
Finally, connect to the database using the `psql` command shown in the output of
the `tsh db login` command, which looks similar to this:

```code
$ psql "service=<cluster>-aurora user=alice dbname=postgres"
Expand Down
97 changes: 81 additions & 16 deletions docs/pages/database-access/guides/azure-postgres-mysql.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,26 +28,34 @@ This guide will help you to:

## Prerequisites

- Teleport version >= `8.1`.
- Deployed Azure Database for PostgreSQL or MySQL server.
- Azure Active Directory administrative privileges.
- A host, e.g., an Azure VM instance, where you will run the Teleport Database
Service.

(!docs/pages/includes/user-client-prereqs.mdx!)

(!docs/pages/includes/tctl.mdx!)

## Step 1/4. Install and configure Teleport

### Set up Teleport Auth and Proxy Services
### Set up the Teleport Auth and Proxy Services

(!docs/pages/includes/database-access/start-auth-proxy.mdx!)

### Set up Teleport Database Service
### Set up the Teleport Database Service

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

Start Teleport Database Service. Make sure to update `--auth-server` to point to
<ScopedBlock scope={["oss", "enterprise"]}>

Start the Teleport Database Service. Make sure to update `--auth-server` to point to
your Teleport Proxy Service address and `--uri` to the Azure database server
endpoint.

<Tabs>
<TabItem label="PostgreSQL">

```bash
$ teleport db start \
--token=/tmp/token \
Expand All @@ -57,8 +65,10 @@ endpoint.
--uri=example.postgres.database.azure.com:5321 \
--labels=env=dev
```

</TabItem>
<TabItem label="MySQL">

```bash
$ teleport db start \
--token=/tmp/token \
Expand All @@ -68,15 +78,54 @@ endpoint.
--uri=example.mysql.database.azure.com:3306 \
--labels=env=dev
```

</TabItem>
</Tabs>

</ScopedBlock>
<ScopedBlock scope={["cloud"]}>

Start the Teleport Database Service. Make sure to update `--auth-server` to point to
your Teleport Cloud tenant address and `--uri` to the Azure database server
endpoint.

<Tabs>
<TabItem label="PostgreSQL">

```bash
$ teleport db start \
--token=/tmp/token \
--auth-server=mytenant.teleport.sh \
--name=azure-db \
--protocol=postgres \
--uri=example.postgres.database.azure.com:5321 \
--labels=env=dev
```

</TabItem>
<TabItem label="MySQL">

```bash
$ teleport db start \
--token=/tmp/token \
--auth-server=mytenant.teleport.sh \
--name=azure-db \
--protocol=mysql \
--uri=example.mysql.database.azure.com:3306 \
--labels=env=dev
```

</TabItem>
</Tabs>

</ScopedBlock>

<Admonition type="tip">
You can start Teleport Database Service using a configuration file instead of
CLI flags. See [YAML reference](../reference/configuration.mdx).
You can start the Teleport Database Service using a configuration file instead of
CLI flags. See the [YAML reference](../reference/configuration.mdx).
</Admonition>

### Create Teleport user
### Create a Teleport user

(!docs/pages/includes/database-access/create-user.mdx!)

Expand All @@ -86,11 +135,11 @@ To authenticate with PostgreSQL or MySQL databases, Teleport Database Service
needs to obtain access tokens from Azure AD. There are a couple of ways to
achieve that:

- Database Service can be registered as an Azure AD application (via AD's "App
- The Database Service can be registered as an Azure AD application (via AD's "App
registrations") and configured with its credentials. This is only recommended
for development and testing purposes since it requires Azure credentials to
be present in the Database Service's environment.
- Database Service can run on an Azure VM with attached managed identity. This
- The Database Service can run on an Azure VM with attached managed identity. This
is the recommended way of deploying the Database Service in production since
it eliminates the need to manage Azure credentials.

Expand Down Expand Up @@ -142,10 +191,10 @@ achieve that:

![Registered app secrets](../../../img/database-access/guides/azure/[email protected])

Teleport Database Service uses Azure SDK's default credential provider chain to
The Teleport Database Service uses Azure SDK's default credential provider chain to
look for credentials. Refer to [Authentication methods](https://docs.microsoft.com/en-us/azure/developer/go/azure-sdk-authorization)
to pick a method suitable for your use-case. For example, to use
environment-based authentication with a client secret, Database Service should
environment-based authentication with a client secret, the Database Service should
have the following environment variables set:

```bash
Expand All @@ -159,7 +208,7 @@ achieve that:
## Step 3/4. Create Azure database users

To let Teleport connect to your Azure database authenticating as a service
principal you need to create Azure AD users for that principal in the database.
principal, you need to create Azure AD users for that principal in the database.

### Assign Azure AD administrator

Expand Down Expand Up @@ -227,9 +276,11 @@ You can create multiple database users for the same service principal.

## Step 4/4. Connect

Log into your Teleport cluster. Your Azure database should appear in the list of
Log in to your Teleport cluster. Your Azure database should appear in the list of
available databases:

<ScopedBlock scope={["oss", "enterprise"]}>

```code
$ tsh login --proxy=teleport.example.com --user=alice
$ tsh db ls
Expand All @@ -238,14 +289,28 @@ $ tsh db ls
# azure-db env=dev
```

Fetch short-lived client certificate for it using `tsh db login` command:
</ScopedBlock>
<ScopedBlock scope={["cloud"]}>

```code
$ tsh login --proxy=mytenant.teleport.sh --user=alice
$ tsh db ls
# Name Description Labels
# -------- ------------------- -------
# azure-db env=dev
```

</ScopedBlock>

Fetch a short-lived client certificate for your Azure database using the
`tsh db login` command:

```code
$ tsh db login --db-user=teleport azure-db
```

<Admonition type="tip">
You can be logged into multiple databases simultaneously.
You can be logged in to multiple databases simultaneously.
</Admonition>

Now connect to the database:
Expand All @@ -256,7 +321,7 @@ $ tsh db connect azure-db

<Admonition type="note">
The appropriate database command-line client (`psql`, `mysql`) should be
available in PATH of the machine you're running `tsh db connect` from.
available in the `PATH` of the machine you're running `tsh db connect` from.
</Admonition>

To log out of the database and remove credentials:
Expand Down
Loading