mirror of
https://github.com/gravitational/teleport.git
synced 2026-10-11 22:49:54 +00:00
mica
2f0c4b6b7a
* docs: critical and high sev agent blockers * Fix high-severity documentation issues found during audit: Rewrite awsoidc-integration.mdx verification section to show expected output and clarify that tctl get does not validate the AWS trust relationship. Correct EKS SSO claim to distinguish IAM role ARN from STS session ARN. Revert redis-create-users.mdx to original secure guidance (unsubstantiated claim, broken ACL). Add eice deprecation note to ec2-config.mdx. Fix numbered list in kubernetes-oidc-join-token.mdx. * Removed the false claim that TLS routing 'routes traffic locally without the reverse tunnel', removed the blanket 'replace port 443' instruction that would break tsh login, and replaced the misleading admonition that presented elastic as a working alias with a clear note that elasticsearch is the only valid value and the CLI doesn't validate input * Added the requirement for iam:GetRole when using SSO roles, with an explanation of what happens without it, and Split the CA trust instruction into self-hosted vs Cloud paths. * linter casing * linter casing * post-review feedback for ptgott - removed admonition tags, added tls info to prereq/rephrased for user or admin * post-feedback from zmb3: cut down tls routing info, clarify the labeling of the CA bundle * fold CA admonition into prose, clarify server.cas naming * feedback: db entries for single-node deployments and NAT hairpinning limitations * single note include addition for mysql and cockroach dbs * removing duplicate note for headless environments * feedback: Expanded tsh proxy db command with full working command, reduced admonition clutter, and in edition-prereqs I split the guidance into two bullets for tctl and tctl commands * Documents the correct critical endpoint and distinguishes it from optional metadata access in mysql-postgres-mariadb * corrected the China region hostname per verified Codex feedback * added identity.pem to connection string * update tbot instance re-creation tip * edit hostname to appease linter. users are already instructed to replace host with their own (line 15) so this is sufficent * edit hostname to appease linter. plain placeholder is clear enough * casing linter appeasement * moved mysql-postgres-mariadb admonition to troubleshooting, style changes
366 lines
12 KiB
Plaintext
366 lines
12 KiB
Plaintext
---
|
|
title: Database Access with Amazon RDS and Aurora for PostgreSQL/MySQL/MariaDB
|
|
sidebar_label: PostgreSQL/MySQL/MariaDB
|
|
description: How to configure Teleport database access with Amazon RDS and Aurora for PostgreSQL, MySQL and MariaDB.
|
|
tags:
|
|
- how-to
|
|
- zero-trust
|
|
- infrastructure-identity
|
|
- aws
|
|
page_type: how-to
|
|
---
|
|
|
|
(!docs/pages/includes/database-access/db-introduction.mdx dbType="Amazon RDS or Aurora" dbConfigure="with IAM authentication"!)
|
|
|
|
## How it works
|
|
|
|
(!docs/pages/includes/database-access/how-it-works/iam.mdx db="RDS" cloud="AWS"!)
|
|
|
|
<Tabs>
|
|
<TabItem label="Self-Hosted">
|
|
|
|
</TabItem>
|
|
<TabItem label="Cloud-Hosted">
|
|
|
|
</TabItem>
|
|
|
|
</Tabs>
|
|
|
|
(!docs/pages/includes/database-access/auto-discovery-tip.mdx dbType="RDS" providerType="AWS" !)
|
|
|
|
## Prerequisites
|
|
|
|
(!docs/pages/includes/edition-prereqs-tabs.mdx!)
|
|
|
|
<Admonition type="warning" title="Supported versions">
|
|
|
|
Before you provision a database for this guide, confirm it isn't one of the
|
|
following, since neither supports IAM authentication and Teleport cannot
|
|
connect to them:
|
|
|
|
- Aurora Serverless v1.
|
|
- RDS MariaDB versions lower than 10.6.
|
|
|
|
We recommend upgrading Aurora Serverless v1 to [Aurora Serverless
|
|
v2](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-serverless-v2.html),
|
|
which supports IAM authentication.
|
|
|
|
</Admonition>
|
|
|
|
- AWS account with RDS and Aurora databases and permissions to create and attach
|
|
IAM policies.
|
|
|
|
<Admonition type="warning" title="IAM authentication">
|
|
Your RDS and Aurora databases must have password and IAM authentication
|
|
enabled.
|
|
|
|
If IAM authentication is not enabled on the target RDS and Aurora databases,
|
|
the Database Service will attempt to enable IAM authentication by modifying
|
|
them using respective APIs.
|
|
</Admonition>
|
|
|
|
- A Linux host or Amazon Elastic Kubernetes Service cluster where you will run
|
|
the Teleport Database Service, which proxies connections to your RDS
|
|
databases.
|
|
|
|
- (!docs/pages/includes/tctl.mdx!)
|
|
|
|
- At least one user that allows IAM authentication on your databases. See
|
|
[Creating a database account using IAM
|
|
authentication](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/UsingWithRDS.IAMDBAuth.DBAccounts.html)
|
|
for more information. This guide assumes that your IAM user is called `alice`.
|
|
|
|
<details>
|
|
<summary>Examples of enabling an IAM user</summary>
|
|
|
|
See below how to enable IAM authentication for the user `alice` on 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>
|
|
|
|
</details>
|
|
|
|
If you plan to run the Teleport Database Service on Kubernetes, you will need
|
|
the following:
|
|
|
|
- The `aws` CLI in your PATH. Install it by following the [AWS
|
|
documentation](https://aws.amazon.com/cli/).
|
|
|
|
- An IAM OIDC provider running in your Kubernetes cluster. See the [AWS
|
|
documentation](https://docs.aws.amazon.com/eks/latest/userguide/enable-iam-roles-for-service-accounts.html)
|
|
for how to create an IAM OIDC provider.
|
|
|
|
To check whether you have an IAM OIDC provider running in your cluster, run
|
|
the following `aws` command, assigning <Var name="eks-region" /> to the
|
|
region where your EKS cluster is running and <Var name="cluster-name" /> to
|
|
the name of your Kubernetes cluster:
|
|
|
|
```code
|
|
$ aws --region=<Var name="eks-region" /> eks describe-cluster --name <Var name="cluster-name"/> --query "cluster.identity.oidc.issuer" --output text
|
|
```
|
|
|
|
If you have an IAM OIDC provider associated with your cluster, this command
|
|
will print its ID.
|
|
|
|
- The [`jq` CLI tool](https://jqlang.github.io/jq/), which we use to process
|
|
JSON data in this guide.
|
|
|
|
## Step 1/5. Create a Teleport user
|
|
|
|
(!docs/pages/includes/database-access/create-user.mdx!)
|
|
|
|
## Step 2/5. Create a Database Service configuration
|
|
|
|
In this section, you will configure the Teleport Database Service. To do so, you
|
|
will:
|
|
|
|
- Create a join token for the service to demonstrate trust with your Teleport
|
|
cluster.
|
|
- Set up your package manager so you can install and run the Database Service.
|
|
- Generate a configuration for the Database Service.
|
|
|
|
### Create a join token
|
|
|
|
Establish trust between the Teleport Database Service and your Teleport cluster
|
|
by creating a join token.
|
|
|
|
Generate a join token by running the following command on your workstation:
|
|
|
|
```code
|
|
$ tctl tokens add --type=db
|
|
```
|
|
|
|
The next step depends on how you plan to run the Teleport Database Service:
|
|
|
|
<Tabs>
|
|
<TabItem label="Linux Server">
|
|
|
|
Save the token in a file called `/tmp/token` on the host that will run the
|
|
Database Service.
|
|
|
|
</TabItem>
|
|
<TabItem label="Kubernetes Cluster">
|
|
|
|
Later in this guide, you will use this join token when configuring the Teleport
|
|
Database Service.
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
(!docs/pages/includes/database-access/alternative-methods-join.mdx!)
|
|
|
|
### Prepare your environment
|
|
|
|
Next, get your environment ready to run the Teleport Database Service:
|
|
|
|
<Tabs>
|
|
<TabItem label="Linux Host">
|
|
|
|
(!docs/pages/includes/install-linux.mdx!)
|
|
|
|
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=rds-example \
|
|
--proxy=<Var name="example.teleport.sh:443" /> \
|
|
--protocol=<Var name="protocol" /> \
|
|
--uri=<Var name="endpoint:port" /> \
|
|
--labels=env=dev \
|
|
--token=/tmp/token
|
|
```
|
|
|
|
The command will generate a Teleport Database Service configuration file and
|
|
place it at the `/etc/teleport.yaml` location.
|
|
|
|
</TabItem>
|
|
<TabItem label="Kubernetes Cluster">
|
|
|
|
(!docs/pages/includes/kubernetes-access/helm/helm-repo-add.mdx!)
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
## Step 3/5. Create IAM policies for Teleport
|
|
|
|
(!docs/pages/includes/database-access/create-iam-role-step-description.mdx accessFor="RDS instances and Aurora clusters" !)
|
|
|
|
### Create an IAM role for Teleport
|
|
|
|
(!docs/pages/includes/aws-credentials.mdx service="the Database Service"!)
|
|
|
|
### Grant permissions
|
|
|
|
Attach the following AWS IAM permissions to the Database Service IAM role:
|
|
|
|
(!docs/pages/includes/database-access/reference/aws-iam/rds/access-policy.mdx!)
|
|
|
|
## Step 4/5. Start the Database Service
|
|
|
|
Start the Teleport Database Service in your environment:
|
|
|
|
<Tabs>
|
|
<TabItem label="Linux Host">
|
|
|
|
(!docs/pages/includes/start-teleport.mdx service="the Database Service"!)
|
|
|
|
</TabItem>
|
|
<TabItem label="Kubernetes Cluster">
|
|
|
|
Retrieve the join token you created earlier in this guide by running the
|
|
following command and copying a token with the `Db` type:
|
|
|
|
```code
|
|
$ tctl tokens ls
|
|
Token Type Labels Expiry Time (UTC)
|
|
-------------------------------- ---- ------ ----------------------------
|
|
(=presets.tokens.first=) Db 14 Jun 23 21:21 UTC (20m15s)
|
|
```
|
|
|
|
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="endpoint:port" /> to the host **and port** of your
|
|
RDS database (e.g., `myrds.us-east-1.rds.amazonaws.com:5432`). Assign <Var
|
|
name="aws-account" /> to your AWS account ID. Set `enterprise` to false if you
|
|
are using Teleport Community Edition:
|
|
|
|
```yaml
|
|
authToken: <Var name="token" />
|
|
proxyAddr: <Var name="example.teleport.sh:443" />
|
|
roles: db
|
|
enterprise: true
|
|
databases:
|
|
- name: example
|
|
uri: "<Var name="endpoint:port" />"
|
|
protocol: <Var name="protocol" />
|
|
static_labels:
|
|
env: dev
|
|
annotations:
|
|
serviceAccount:
|
|
eks.amazonaws.com/role-arn: arn:aws:iam::<Var name="aws-account" />:role/teleport-rds-role
|
|
```
|
|
|
|
Get the version of Teleport to install. If you have automatic agent updates enabled in your cluster, query the latest Teleport version that is compatible with the updater:
|
|
|
|
```code
|
|
$ TELEPORT_VERSION="$(curl https://<Var name="example.teleport.sh:443" />/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"
|
|
```
|
|
|
|
Otherwise, get the version of your Teleport cluster:
|
|
|
|
```code
|
|
$ TELEPORT_VERSION="$(curl https://<Var name="example.teleport.sh:443" />/v1/webapi/ping | jq -r '.server_version')"
|
|
```
|
|
|
|
|
|
Install the Helm chart for Teleport Agent services, `teleport-kube-agent`:
|
|
|
|
```code
|
|
$ helm -n teleport-agent install teleport-kube-agent teleport/teleport-kube-agent \
|
|
--values values.yaml --create-namespace --version $TELEPORT_VERSION
|
|
```
|
|
|
|
Make sure that the Teleport Agent pod is running. You should see one
|
|
`teleport-kube-agent` pod with a single ready container:
|
|
|
|
```code
|
|
$ kubectl -n teleport-agent get pods
|
|
NAME READY STATUS RESTARTS AGE
|
|
teleport-kube-agent-0 1/1 Running 0 32s
|
|
```
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
## Step 5/5. Connect
|
|
|
|
Once the Database Service has started and joined the cluster, log in as the
|
|
`alice` user you created earlier to see the registered databases:
|
|
|
|
```code
|
|
$ tsh login --proxy=<Var name="example.teleport.sh:443" /> --user=alice
|
|
$ tsh db ls
|
|
# Name Description Labels
|
|
# ----------- ----------- --------
|
|
# rds-example env=dev
|
|
```
|
|
|
|
(!docs/pages/includes/database-access/pg-mysql-connect.mdx dbUser="alice" dbService="rds-example"!)
|
|
|
|
Log out of the database and remove credentials:
|
|
|
|
```code
|
|
$ tsh db logout rds-example
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Databases not appearing
|
|
|
|
The Database Service downloads the RDS CA certificate bundle on startup from
|
|
the following endpoint (required for mTLS connections to your database):
|
|
|
|
```text
|
|
https://truststore.pki.rds.amazonaws.com/<region>/<region>-bundle.pem
|
|
```
|
|
|
|
For GovCloud regions, the host is `truststore.pki.us-gov-west-1.rds.amazonaws.com`.
|
|
For China regions, it is `rds-truststore.s3.cn-north-1.amazonaws.com.cn`.
|
|
|
|
If databases do not appear in `tctl db ls` within 60 seconds of starting the
|
|
service:
|
|
|
|
1. Ensure this endpoint is reachable from the host running the Database Service.
|
|
1. Enable DEBUG logging by setting `teleport.log.severity: DEBUG` in
|
|
`teleport.yaml`, then check the logs for download failures.
|
|
|
|
Access to the RDS API (`rds.<region>.amazonaws.com`) is used on a best-effort
|
|
basis to fetch additional metadata (tags, engine versions), but it is not
|
|
required for database registration.
|
|
|
|
(!docs/pages/includes/database-access/aws-troubleshooting.mdx!)
|
|
|
|
(!docs/pages/includes/database-access/aws-troubleshooting-max-policy-size.mdx!)
|
|
|
|
(!docs/pages/includes/database-access/pg-cancel-request-limitation.mdx!)
|
|
|
|
(!docs/pages/includes/database-access/psql-ssl-syscall-error.mdx!)
|
|
|
|
## Next steps
|
|
|
|
(!docs/pages/includes/database-access/guides-next-steps.mdx!)
|
|
- Set up [automatic database user provisioning](../../../auto-user-provisioning/auto-user-provisioning.mdx).
|
|
|