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

[v16] [docs] update RDS guides #42728

Merged
merged 3 commits into from
Jun 11, 2024
Merged

[v16] [docs] update RDS guides #42728

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
219df49
update RDS guide
GavinFrazar May 17, 2024
584d0d6
fixup aws db slugs
GavinFrazar May 21, 2024
80d50ff
use Cloud-Hosted phrasing
GavinFrazar May 21, 2024
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
46 changes: 23 additions & 23 deletions docs/config.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1275,52 +1275,52 @@
"slug": "/database-access/enroll-aws-databases/",
"entries": [
{
"title": "AWS Cross-Account Database Access",
"slug": "/database-access/enroll-aws-databases/aws-cross-account/"
},
{
"title": "AWS DynamoDB",
"title": "Amazon DynamoDB",
"slug": "/database-access/enroll-aws-databases/aws-dynamodb/"
},
{
"title": "AWS OpenSearch",
"slug": "/database-access/enroll-aws-databases/aws-opensearch/"
"title": "Amazon ElastiCache and MemoryDB for Redis",
"slug": "/database-access/enroll-aws-databases/redis-aws/"
},
{
"title": "AWS RDS Proxy for MariaDB/MySQL",
"slug": "/database-access/enroll-aws-databases/rds-proxy-mysql/"
"title": "Amazon Keyspaces (Apache Cassandra)",
"slug": "/database-access/enroll-aws-databases/aws-cassandra-keyspaces/"
},
{
"title": "Microsoft SQL Server with Active Directory authentication",
"slug": "/database-access/enroll-aws-databases/sql-server-ad/"
"title": "Amazon OpenSearch",
"slug": "/database-access/enroll-aws-databases/aws-opensearch/"
},
{
"title": "AWS ElastiCache and AWS MemoryDB for Redis",
"slug": "/database-access/enroll-aws-databases/redis-aws/"
"title": "Amazon RDS Proxy for MariaDB/MySQL",
"slug": "/database-access/enroll-aws-databases/rds-proxy-mysql/"
},
{
"title": "AWS Keyspaces (Apache Cassandra)",
"slug": "/database-access/enroll-aws-databases/aws-cassandra-keyspaces/"
"title": "Amazon RDS Proxy for Microsoft SQL Server",
"slug": "/database-access/enroll-aws-databases/rds-proxy-sqlserver/"
},
{
"title": "AWS RDS Proxy for PostgreSQL",
"title": "Amazon RDS Proxy for PostgreSQL",
"slug": "/database-access/enroll-aws-databases/rds-proxy-postgres/"
},
{
"title": "Redshift Serverless on AWS",
"slug": "/database-access/enroll-aws-databases/redshift-serverless/"
"title": "Amazon RDS and Aurora",
"slug": "/database-access/enroll-aws-databases/rds/"
},
{
"title": "AWS RDS Proxy for Microsoft SQL Server",
"slug": "/database-access/enroll-aws-databases/rds-proxy-sqlserver/"
"title": "Amazon RDS for Microsoft SQL Server",
"slug": "/database-access/enroll-aws-databases/sql-server-ad/"
},
{
"title": "Redshift on AWS",
"title": "Amazon Redshift",
"slug": "/database-access/enroll-aws-databases/postgres-redshift/"
},
{
"title": "AWS RDS and Aurora",
"slug": "/database-access/enroll-aws-databases/rds/"
"title": "Amazon Redshift Serverless",
"slug": "/database-access/enroll-aws-databases/redshift-serverless/"
},
{
"title": "Cross-Account Access",
"slug": "/database-access/enroll-aws-databases/aws-cross-account/"
}
]
},
Expand Down
18 changes: 9 additions & 9 deletions docs/pages/database-access/enroll-aws-databases.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,14 +17,14 @@ Access](./enroll-aws-databases/aws-cross-account.mdx).
Read the following guides for how to protect a specific AWS-managed database
with Teleport:

- [Amazon Redshift](./enroll-aws-databases/postgres-redshift.mdx)
- [Amazon Redshift Serverless](./enroll-aws-databases/redshift-serverless.mdx)
- [Amazon RDS](./enroll-aws-databases/rds.mdx)
- [Amazon RDS for SQL Server](./enroll-aws-databases/sql-server-ad.mdx)
- [Amazon RDS Proxy for PostgreSQL](./enroll-aws-databases/rds-proxy-postgres.mdx)
- [Amazon RDS Proxy for Microsoft SQL Server](./enroll-aws-databases/rds-proxy-sqlserver.mdx)
- [Amazon RDS Proxy MySQL](./enroll-aws-databases/rds-proxy-mysql.mdx)
- [Amazon OpenSearch](./enroll-aws-databases/aws-opensearch.mdx)
- [Amazon DynamoDB](./enroll-aws-databases/aws-dynamodb.mdx)
- [Amazon Keyspaces (Apache Cassandra)](./enroll-aws-databases/aws-cassandra-keyspaces.mdx)
- [Amazon ElastiCache and MemoryDB for Redis](./enroll-aws-databases/redis-aws.mdx)
- [Amazon Keyspaces (Apache Cassandra)](./enroll-aws-databases/aws-cassandra-keyspaces.mdx)
- [Amazon OpenSearch](./enroll-aws-databases/aws-opensearch.mdx)
- [Amazon RDS Proxy MySQL](./enroll-aws-databases/rds-proxy-mysql.mdx)
- [Amazon RDS Proxy for Microsoft SQL Server](./enroll-aws-databases/rds-proxy-sqlserver.mdx)
- [Amazon RDS Proxy for PostgreSQL](./enroll-aws-databases/rds-proxy-postgres.mdx)
- [Amazon RDS and Aurora](./enroll-aws-databases/rds.mdx)
- [Amazon RDS for SQL Server](./enroll-aws-databases/sql-server-ad.mdx)
- [Amazon Redshift Serverless](./enroll-aws-databases/redshift-serverless.mdx)
- [Amazon Redshift](./enroll-aws-databases/postgres-redshift.mdx)
78 changes: 24 additions & 54 deletions docs/pages/database-access/enroll-aws-databases/rds.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,11 @@ description: How to configure Teleport database access with AWS RDS and Aurora f
(!docs/pages/includes/database-access/how-it-works/iam.mdx db="RDS" cloud="AWS"!)

<Tabs>
<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">
![Teleport Database Access RDS Self-Hosted](../../../img/database-access/guides/rds_selfhosted.png)
<TabItem label="Self-Hosted">
![Teleport Architecture RDS Self-Hosted](../../../img/database-access/guides/rds_selfhosted.png)
</TabItem>
<TabItem scope={["cloud"]} label="Teleport Enterprise Cloud">
![Teleport Database Access RDS Cloud](../../../img/database-access/guides/rds_cloud.png)
<TabItem label="Cloud-Hosted">
![Teleport Architecture RDS Cloud-Hosted](../../../img/database-access/guides/rds_cloud.png)
</TabItem>

</Tabs>
Expand Down Expand Up @@ -136,43 +136,24 @@ Next, get your environment ready to run the Teleport Database Service:

(!docs/pages/includes/install-linux.mdx!)

Generate a configuration for the Teleport Database Service:

Generate a configuration file for the Teleport Database Service. Run one of the
following commands, depending on whether you want to proxy an AWS Aurora or
Amazon RDS instance.

Assign <Var name="example.teleport.sh:443" /> to the host **and port** of your
Teleport Proxy Service or Enterprise Cloud site. Assign <Var name="us-west-1" />
to the region associated with the RDS database.

Run the following command to proxy an AWS Aurora cluster, assigning <Var
name="RDS_URI" /> to your cluster's domain name and port and <Var
name="protocol" /> to either `postgres` or `mysql`, depending on the database
you want to proxy:

```code
$ sudo teleport db configure create \
-o file \
--name="postgres-rds" \
--proxy=<Var name="example.teleport.sh:443" /> \
--protocol=<Var name="protocol" /> \
--uri=<Var name="RDS_URI" /> \
--token=/tmp/token
```

Run the following command to proxy an AWS RDS instance, assigning <Var
name="RDS_URI" /> to your instance's domain name and port and <Var
name="protocol" /> to either `postgres` or `mysql`, depending on the database
you want to proxy:
Provide the following information and then generate a configuration file for the
Teleport Database Service:
- <Var name="example.teleport.sh:443" /> The host **and port** of your Teleport
Proxy Service or cloud-hosted Teleport Enterprise site
- <Var name="protocol" /> The protocol of the database you want to proxy, either
`mysql` or `postgres`
- <Var name="endpoint:port" /> The endpoint **and port** of the database - the
cluster endpoint for Aurora or the instance endpoint for an RDS instance, e.g.
`myrds.us-east-1.rds.amazonaws.com:5432`

```code
$ sudo teleport db configure create \
-o file \
--name="postgres-rds" \
--name=rds-example \
--proxy=<Var name="example.teleport.sh:443" /> \
--protocol=<Var name="protocol" /> \
--uri=<Var name="RDS_URI" /> \
--uri=<Var name="endpoint:port" /> \
--labels=env=dev \
--token=/tmp/token
```

Expand Down Expand Up @@ -339,7 +320,7 @@ Token Type Labels Expiry Time (UTC)
Create a Helm values file called `values.yaml`, assigning <Var name="token" />
to the value of the join token you retrieved above, <Var
name="example.teleport.sh:443" /> to the host **and port** of your Teleport
Proxy Service, and <Var name="rds-uri" /> to the host **and port** of your RDS
Proxy Service, and <Var name="endpoint:port" /> to the host **and port** of your RDS
database (e.g., `myrds.us-east-1.rds.amazonaws.com:5432`):

```var
Expand All @@ -348,12 +329,10 @@ proxyAddr: <Var name="example.teleport.sh:443" />
roles: db
databases:
- name: example
uri: "<Var name="rds-uri" />"
uri: "<Var name="endpoint:port" />"
protocol: <Var name="protocol" />
static_labels:
env: dev
aws:
region: "<Var name="rds-region" />"
annotations:
serviceAccount:
eks.amazonaws.com/role-arn: arn:aws:iam::<Var name="aws-account" />:role/teleport-rds-role
Expand Down Expand Up @@ -421,24 +400,15 @@ Once the Database Service has started and joined the cluster, log in as the
```code
$ tsh login --proxy=<Var name="example.teleport.sh:443" /> --user=alice
$ tsh db ls
# Name Description Labels
# ------------ ----------- --------
# postgres-rds
```

Retrieve credentials for a database and connect to it as the `alice` user,
assigning <Var name="postgres-rds" /> to the name of a database resource listed
by `tsh db ls`:

```code
$ tsh db connect <Var name="postgres-rds" /> --db-user=alice
# Name Description Labels
# ----------- ----------- --------
# rds-example env=dev
```

You can optionally specify the database name to use by default when connecting
to the database instance:
Retrieve credentials for the database and connect to it as the `alice` user:

```code
$ tsh db connect --db-user=postgres --db-name=postgres <Var name="postgres-rds" />
$ tsh db connect --db-user=postgres --db-name=postgres rds-example
```

<Admonition type="note" title="Note">
Expand All @@ -449,7 +419,7 @@ $ tsh db connect --db-user=postgres --db-name=postgres <Var name="postgres-rds"
Log out of the database and remove credentials:

```code
$ tsh db logout <Var name="postgres-rds" />
$ tsh db logout rds-example
```

## Troubleshooting
Expand Down
64 changes: 29 additions & 35 deletions docs/pages/includes/database-access/rds-proxy.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,11 @@
(!docs/pages/includes/database-access/how-it-works/iam.mdx db="RDS Proxy" cloud="AWS"!)

<Tabs>
<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">
![Teleport Database Access RDS Proxy Self-Hosted](../../../img/database-access/guides/rds-proxy_selfhosted.png)
<TabItem label="Self-Hosted">
![Teleport Architecture RDS Proxy Self-Hosted](../../../img/database-access/guides/rds-proxy_selfhosted.png)
</TabItem>
<TabItem scope={["cloud"]} label="Teleport Enterprise Cloud">
![Teleport Database Access RDS Proxy Cloud](../../../img/database-access/guides/rds-proxy_cloud.png)
<TabItem label="Cloud-Hosted">
![Teleport Architecture RDS Proxy Cloud-Hosted](../../../img/database-access/guides/rds-proxy_cloud.png)
</TabItem>

</Tabs>
Expand All @@ -34,54 +34,49 @@ automatically enroll all AWS databases in your infrastructure.
Service.
- (!docs/pages/includes/tctl.mdx!)

## Step 1/5. Create a Database Service configuration
## Step 1/7. Install Teleport

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

(!docs/pages/includes/database-access/alternative-methods-join.mdx!)
(!docs/pages/includes/install-linux.mdx!)

Install Teleport on the host where you will run the Teleport Database Service:
## Step 2/7. Create a Teleport Database Service configuration

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

(!docs/pages/includes/aws-credentials.mdx service="the Teleport Database Service"!)
(!docs/pages/includes/database-access/alternative-methods-join.mdx!)

Create the Database Service configuration. Replace <Var
name="teleport.example.com" /> with the domain name of your Teleport Proxy
Service or Teleport Cloud account (e.g. `example.teleport.sh`) and
<Var name="DATABASE_URI" /> with the host and port of the database you want to
proxy:
name="teleport.example.com:443" /> with the domain name **and port** of your
Teleport Proxy Service or cloud-hosted Teleport Enterprise account and
<Var name="endpoint:port" /> with the host **and port** of the database endpoint:

```code
$ sudo teleport db configure create \
-o file \
--proxy=<Var name="teleport.example.com"/>:443 \
--uri=<Var name="DATABASE_URI" /> \
--proxy=<Var name="teleport.example.com:443"/> \
--uri=<Var name="endpoint:port" /> \
--protocol={{ protocol }} \
--token=/tmp/token
--token=/tmp/token \
--labels=env=dev
```

The command will generate a Database Service configuration with RDS Proxy
instances auto-discovery enabled on the <Var name="us-west-1" /> region and
The command will generate a Teleport Database Service configuration file and
place it at the `/etc/teleport.yaml` location.

## Step 2/5. Create an IAM policy for Teleport
## Step 3/7. Configure AWS Credentials

(!docs/pages/includes/aws-credentials.mdx service="the Teleport Database Service"!)

## Step 4/7. Create an IAM policy for Teleport

Teleport needs AWS IAM permissions to be able to discover and register RDS
Proxy instances.
Teleport needs AWS IAM permissions to be able to access RDS Proxy instances.

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

## Step 3/5. Start the Database Service
## Step 5/7. Start the Database Service

(!docs/pages/includes/start-teleport.mdx service="the Teleport Database Service"!)

The Database Service will discover all RDS Proxy instances according to the
configuration and register them in the cluster. In addition to the primary
endpoints of the RDS Proxy instances, their custom endpoints will also be
registered.

## Step 4/5. Configure database user credentials
## Step 6/7. Configure database user credentials

The Database Service connects to an RDS Proxy instance using IAM
authentication. In addition, the RDS Proxy instance must also be able to
Expand Down Expand Up @@ -169,21 +164,20 @@ IAMAuth=REQUIRED AuthScheme=SECRETS,SecretArn=arn-of-non-teleport-user,IAMAuth=D
See `aws rds modify-db-proxy help` for more information.
</Admonition>

## Step 5/5. Connect
## Step 7/7. Connect

Once the Database Service has started and joined the cluster, log in to see the
registered databases:
registered database:

```code
$ tsh login --proxy=<Var name="teleport.example.com" /> --user=alice
$ tsh login --proxy=<Var name="teleport.example.com:443" /> --user=alice
$ tsh db ls
Name Description Labels
---------------------------- ------------------------------- -------
rds-proxy RDS Proxy in us-west-1 ...
rds-proxy-my-reader-endpoint RDS Proxy endpoint in us-west-1 ...
```

To retrieve credentials for a database and connect to it:
Retrieve credentials for the database and connect to it as the `alice` user:

```code
$ tsh db connect --db-user=alice --db-name=dev rds-proxy
Expand Down
Loading