
Teleport
Database Access with AWS RDS and Aurora for PostgreSQL, MySQL and MariaDB
- Version 15.x
- Version 14.x
- Version 13.x
- Version 12.x
- Older Versions
- Available for:
- OpenSource
- Team
- Cloud
- Enterprise
Access to AWS or RDS Aurora databases can be provided by Teleport Database Access. This allows for fine-grain access control through Teleport's RBAC.
This guide demonstrates how to use Teleport to connect to AWS or RDS Aurora databases.
In this guide, you will:
- Configure AWS RDS or Aurora databases with IAM authentication.
- Join the AWS RDS or Aurora databases to your Teleport cluster.
- Connect to the AWS RDS or Aurora database via the Teleport Database Service.
Please use the latest version of Teleport Enterprise documentation.
The following products are not compatible with Teleport as they don't support IAM authentication:
- Aurora Serverless v1.
- RDS MariaDB versions lower than 10.6.
We recommend upgrading Aurora Serverless v1 to Aurora Serverless v2, which supports IAM authentication.
Prerequisites
-
A Teleport Team account. If you don't have an account, sign up to begin your free trial.
-
The Enterprise
tctl
admin tool andtsh
client tool, version >= 14.0.0.You can download these tools by visiting your Teleport account workspace.
-
A running Teleport cluster. For details on how to set this up, see the Getting Started guide.
-
The
tctl
admin tool andtsh
client tool version >= 14.0.0.See Installation for details.
-
A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 14.0.0.You can download these tools by visiting your Teleport account workspace.
Please use the latest version of Teleport Enterprise documentation.
To check version information, run the tctl version
and tsh version
commands.
For example:
tctl versionTeleport Enterprise v13.3.9 git:api/14.0.0-gd1e081e go1.21
tsh versionTeleport v13.3.9 go1.21
Proxy version: 13.3.9Proxy: teleport.example.com
- AWS account with RDS and Aurora databases and permissions to create and attach IAM policies. Your RDS and Aurora databases must have password and IAM authentication enabled.
- A Linux host or Amazon Elastic Kubernetes Service cluster where you will run the Teleport Database Service, which proxies connections to your RDS databases.
- A running Teleport Discovery Service if you plan to use Database Auto-Discovery.
- To check that you can connect to your Teleport cluster, sign in with
tsh login
, then verify that you can runtctl
commands on your administrative workstation using your current credentials. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 14.0.0
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
commands on the computer that hosts the Teleport Auth Service for full permissions.
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. -
An IAM OIDC provider running in your Kubernetes cluster. See the AWS documentation 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 eks-region to the region where your EKS cluster is running and cluster-name to the name of your Kubernetes cluster:aws --region=eks-region eks describe-cluster --name cluster-name --query "cluster.identity.oidc.issuer" --output textIf you have an IAM OIDC provider associated with your cluster, this command will print its ID.
-
The
jq
CLI tool, which we use to process JSON data in this guide.
Step 1/6. Create a Teleport user
To modify an existing user to provide access to the Database Service, see Database Access Access Controls
Create a local Teleport user with the built-in access
role:
tctl users add \ --roles=access \ --db-users=\* \ --db-names=\* \ alice
Create a local Teleport user with the built-in access
and requester
roles:
tctl users add \ --roles=access,requester \ --db-users=\* \ --db-names=\* \ alice
Flag | Description |
---|---|
--roles | List of roles to assign to the user. The builtin access role allows them to connect to any database server registered with Teleport. |
--db-users | List of database usernames the user will be allowed to use when connecting to the databases. A wildcard allows any user. |
--db-names | List of logical databases (aka schemas) the user will be allowed to connect to within a database server. A wildcard allows any database. |
Database names are only enforced for PostgreSQL and MongoDB databases.
For more detailed information about database access controls and how to restrict access see RBAC documentation.
Step 2/6. 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:
tctl tokens add --type=db
The next step depends on how you plan to run the Teleport Database Service:
Save the token in a file called /tmp/token
on the host that will run the
Database Service.
Later in this guide, you will use this join token when configuring the Teleport Database Service.
For users with a lot of infrastructure in AWS, or who might create or recreate many instances, consider alternative methods for joining new EC2 instances running Teleport:
Prepare your environment
Next, get your environment ready to run the Teleport Database Service:
Install Teleport on the host where you will run the Teleport Database Service:
Select an edition, then follow the instructions for that edition to install Teleport.
Teleport Edition
- Teleport Team
- Open Source
- Enterprise
- Enterprise Cloud
curl https://goteleport.com/static/install.sh | bash -s 13.3.9
Before installing a teleport
binary with a version besides
v13, read our compatibility rules to ensure that the
binary is compatible with Teleport Cloud.
When running multiple teleport
binaries within a cluster, the following rules
apply:
- Patch and minor versions are always compatible, for example, any 8.0.1 component will work with any 8.0.3 component and any 8.1.0 component will work with any 8.3.0 component.
- Servers support clients that are 1 major version behind, but do not support
clients that are on a newer major version. For example, an 8.x.x Proxy Service
is compatible with 7.x.x resource services and 7.x.x
tsh
, but we don't guarantee that a 9.x.x resource service will work with an 8.x.x Proxy Service. This also means you must not attempt to upgrade from 6.x.x straight to 8.x.x. You must upgrade to 7.x.x first. - Proxy Services and resource services do not support Auth Services that are on
an older major version, and will fail to connect to older Auth Services by
default. This behavior can be overridden by passing
--skip-version-check
when starting Proxy Services and resource services.
curl https://goteleport.com/static/install.sh | bash -s 14.0.0
Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.ascSource variables about OS version
source /etc/os-releaseAdd the Teleport APT repository for v14. You'll need to update this
file for each major release of Teleport.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v14" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/nullsudo apt-get updatesudo apt-get install teleport-ent
For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips
package instead:
sudo apt-get install teleport-ent-fips
Source variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for v14. You'll need to update this
file for each major release of Teleport.
First, get the major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v14/teleport.repo")"sudo yum install teleport-entTip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips
package instead:
sudo yum install teleport-ent-fips
Source variables about OS version
source /etc/os-releaseAdd the Teleport Zypper repository for v14. You'll need to update this
file for each major release of Teleport.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")Use zypper to add the teleport RPM repo
sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.repo")sudo yum install teleport-entTip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips
package instead:
sudo yum install teleport-ent-fips
Source variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for v14. You'll need to update this
file for each major release of Teleport.
First, get the major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")Use the dnf config manager plugin to add the teleport RPM repo
sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v14/teleport.repo")"Install teleport
sudo dnf install teleport-entTip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips
package instead:
sudo dnf install teleport-ent-fips
Source variables about OS version
source /etc/os-releaseAdd the Teleport Zypper repository.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")Use Zypper to add the teleport RPM repo
sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v14/teleport-zypper.repo")Install teleport
sudo zypper install teleport-ent
For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips
package instead:
sudo zypper install teleport-ent-fips
In the example commands below, update $SYSTEM_ARCH
with the appropriate
value (amd64
, arm64
, or arm
). All example commands using this variable
will update after one is filled out.
curl https://get.gravitational.com/teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-bin.tar.gzshasum -a 256 teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-bin.tar.gzcd teleport-entsudo ./install
For FedRAMP/FIPS-compliant installations of Teleport Enterprise, package URLs will be slightly different:
curl https://get.gravitational.com/teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-fips-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-fips-bin.tar.gzshasum -a 256 teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-fips-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-fips-bin.tar.gzcd teleport-entsudo ./install
OS repository channels
The following channels are available for APT, YUM, and Zypper repos. They may be used in place of
stable/v14
anywhere in the Teleport documentation.
Channel name | Description |
---|---|
stable/<major> | Receives releases for the specified major release line, i.e. v14 |
stable/cloud | Rolling channel that receives releases compatible with current Cloud version |
stable/rolling | Rolling channel that receives all published Teleport releases |
Please use the latest version of Teleport Enterprise documentation.
Databases can be registered dynamically by Discovery Service, tctl
, etc.
Generate a Database Service configuration that monitors the dynamic database resources:
sudo teleport db configure create \ -o file \ --proxy=mytenant.teleport.sh:443 \ --token=/tmp/token \ --dynamic-resources-labels env=prod
This command will place the Database Service configuration at the
/etc/teleport.yaml
location.
In your Teleport Discovery Service's configuration, use AWS matcher type
rds
, and update region
and tags
that match your RDS
databases:
discovery_service:
enabled: "yes"
aws:
- types: ["rds"]
regions: ["us-west-1"]
tags:
"env": "prod" # Match database resource tags where tag:env=prod
Restart the Discovery Service.
To allow Helm to install charts that are hosted in the Teleport Helm repository, use helm repo add
:
helm repo add teleport https://charts.releases.teleport.dev
To update the cache of charts from the remote repository, run helm repo update
:
helm repo update
Step 3/6. Create IAM policies for Teleport
The Teleport Database Service needs AWS IAM permissions to be able to:
- Configure IAM authentication.
In this step, we will show you how to provide the Teleport Database Service access to AWS credentials:
Follow these instructions on your Linux host.
Grant the Database Service access to credentials that it can use to authenticate to AWS. If you are running the Database Service on an EC2 instance, you should use the EC2 Instance Metadata Service method. Otherwise, you must use environment variables:
Teleport will detect when it is running on an EC2 instance and use the Instance Metadata Service to fetch credentials.
The EC2 instance should be configured to use an EC2 instance profile. For more information, see: Using Instance Profiles.
Teleport's built-in AWS client reads credentials from the following environment variables:
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_DEFAULT_REGION
When you start the Database Service, the service reads environment variables from a
file at the path /etc/default/teleport
. Obtain these credentials from your
organization. Ensure that /etc/default/teleport
has the following content,
replacing the values of each variable:
AWS_ACCESS_KEY_ID=00000000000000000000
AWS_SECRET_ACCESS_KEY=0000000000000000000000000000000000000000
AWS_DEFAULT_REGION=<YOUR_REGION>
Teleport's AWS client loads credentials from different sources in the following order:
- Environment Variables
- Shared credentials file
- Shared configuration file (Teleport always enables shared configuration)
- EC2 Instance Metadata (credentials only)
While you can provide AWS credentials via a shared credentials file or shared
configuration file, you will need to run the Database Service with the AWS_PROFILE
environment variable assigned to the name of your profile of choice.
If you have a specific use case that the instructions above do not account for, consult the documentation for the AWS SDK for Go for a detailed description of credential loading behavior.
Teleport can bootstrap IAM permissions for the Database Service based on its configuration:
Teleport can bootstrap IAM permissions for the Database Service based on
Discovery Service's configuration while bootstrapping the Discovery Service
using the teleport discovery bootstrap
command. You can use this command in
automatic or manual mode:
- In automatic mode, Teleport will attempt to create appropriate IAM policies and attach them to the specified IAM role. This requires IAM permissions to create and attach IAM policies.
- In manual mode, Teleport will print required IAM policies. You can then create
and attach them manually using the AWS management console. Add
--manual
flag to the command to enable manual mode.
teleport discovery bootstrap \ --attach-to-role arn:aws:iam::aws-account-id:role/discovery-iam-role-name \ --policy-name TeleportDatabaseDiscovery \ --database-service-role arn:aws:iam::aws-account-id:role/database-iam-role-name \ --database-service-policy-name TeleportDatabaseAccess \ -c path to Discovery's teleport.yaml
Teleport can bootstrap IAM permissions for the Database Service based on its
configuration using the teleport db configure bootstrap
command. You can use
this command in automatic or manual mode:
- In automatic mode, Teleport will attempt to create appropriate IAM policies and attach them to the specified IAM identity (user or role). This requires IAM permissions to create and attach IAM policies.
- In manual mode, Teleport will print required IAM policies. You can then create and attach them manually using the AWS management console.
Use this command to bootstrap the permissions automatically when your Teleport Database Service runs as an IAM user (for example, uses an AWS credentials file).
teleport db configure bootstrap -c /etc/teleport.yaml --attach-to-user TeleportUser
Use this command to bootstrap the permissions automatically when your Teleport Database Service runs as an IAM role (for example, on an EC2 instance with an attached IAM role).
teleport db configure bootstrap -c /etc/teleport.yaml --attach-to-role TeleportRole
Use this command to display required IAM policies which you will then create in your AWS console:
teleport db configure bootstrap -c /etc/teleport.yaml --manual --attach-to-user arn:aws:iam::123456789012:user/TeleportUser
Use this command to display required IAM policies which you will then create in your AWS console:
teleport db configure bootstrap -c /etc/teleport.yaml --manual --attach-to-role arn:aws:iam::123456789012:role/TeleportRole
When assume_role_arn
is configured for databases or AWS matchers,
teleport db configure bootstrap
will determine permissions required for the
bootstrap target AWS IAM identity using the following logic:
- When the target does not match
assume_role_arn
in any database resource or AWS matcher in the configuration file, the target is assumed to be the Teleport Database Service's AWS IAM identity and permissions are bootstrapped for all the configured static databases and AWS matchers. - When an
--attach-to-role
target matches anassume_role_arn
setting for static databases or AWS matchers in the configuration file, permissions will be bootstrapped only for those static databases or AWS matchers.
You will need to run the bootstrap command once with the Teleport Database
Service's IAM identity as the policy attachment target, and once for each AWS
IAM role that is used for assume_role_arn
.
Alternatively, you can create or print the required IAM policies with the following commands and manually attach them to the IAM role:
teleport db configure aws create-iam --types rds
teleport db configure aws print-iam --types rds
Follow these instructions on your local workstation.
Create an IAM policy document that allows an IAM identity to connect to your RDS
database. Assign rds-region to the name of the AWS region where
your RDS database is running, aws-account to your AWS account
number, and resource-id to the resource ID of your RDS database
or the cluster ID of your Aurora cluster (e.g.,
db-AAAAAAAAAAAAAAAAAAAAAAAAAA
):
cat > connect.json << EOF{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "rds-db:connect" ], "Resource": [ "arn:aws:rds-db:rds-region:aws-account:dbuser:resource-id/*" ] } ]}EOF
Create the IAM policy:
aws iam create-policy --policy-name teleport-rds-policy --policy-document file://connect.json{ "Policy": { "PolicyName": "teleport-rds-policy", "PolicyId": "000000000000000000000", "Arn": "arn:aws:iam::000000000000:policy/teleport-rds-policy", "Path": "/", "DefaultVersionId": "v1", "AttachmentCount": 0, "PermissionsBoundaryUsageCount": 0, "IsAttachable": true, "CreateDate": "2023-07-13T18:03:08+00:00", "UpdateDate": "2023-07-13T18:03:08+00:00" }}
Next, create a trust policy for the teleport-rds-role
, which allows the role
to obtain temporary credentials via the IAM OIDC provider.
Retrieve your OIDC issuer ID, assigning cluster-name to the name of your EKS cluster and eks-region to the AWS region where your EKS cluster is running:
aws eks describe-cluster --name cluster-name --region eks-region | jq -r .cluster.identity.oidc.issuer | grep -Eo "[A-Z0-9]+$"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
Create a file called trustpolicy.json
with the following content, assigning
oidc-issuer to the issuer string you retrieved:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam::aws-account:oidc-provider/oidc.eks.eks-region.amazonaws.com/id/oidc-issuer" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { "oidc.eks.eks-region.amazonaws.com/id/oidc-issuer:aud": "sts.amazonaws.com" } } } ]}
Create an IAM role with your trust policy. On success, the command will show the IAM resource you created:
aws iam create-role --role-name teleport-rds-role --assume-role-policy-document file://trustpolicy.json
Attach the role to the policy you created earlier. On success, this command will show no output:
aws iam attach-role-policy --policy-arn arn:aws:iam::aws-account:policy/teleport-rds-policy --role-name teleport-rds-role
Step 4/6. Start the Database Service
Start the Teleport Database Service in your environment:
Configure the Database Service to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed the Database Service.
On the host where you will run the Database Service, enable and start Teleport:
sudo systemctl enable teleportsudo systemctl start teleport
On the host where you will run the Database Service, create a systemd service configuration for Teleport, enable the Teleport service, and start Teleport:
sudo teleport install systemd -o /etc/systemd/system/teleport.servicesudo systemctl enable teleportsudo systemctl start teleport
You can check the status of the Database Service with systemctl status teleport
and view its logs with journalctl -fu teleport
.
Retrieve the join token you created earlier in this guide by running the
following command and copying a token with the Db
type:
tctl tokens lsToken Type Labels Expiry Time (UTC)-------------------------------- ---- ------ ----------------------------abcd123-insecure-do-not-use-this Db 14 Jun 23 21:21 UTC (20m15s)
Create a Helm values file called values.yaml
, assigning token
to the value of the join token you retrieved above, example.teleport.sh:443 to the host and port of your Teleport
Proxy Service, and rds-uri to the host and port of your RDS
database (e.g., myrds.us-east-1.rds.amazonaws.com:5432
):
authToken: tokenproxyAddr: example.teleport.sh:443roles: dbdatabases:- name: example uri: "rds-uri" protocol: "postgres" static_labels: env: dev aws: region: "rds-region"annotations: serviceAccount: eks.amazonaws.com/role-arn: arn:aws:iam::aws-account:role/teleport-rds-role
Install the Helm chart for Teleport agent services, teleport-kube-agent
:
helm -n teleport install teleport-kube-agent teleport/teleport-kube-agent \ --values values.yaml --create-namespace
Make sure that the Teleport agent pod is running. You should see one
teleport-kube-agent
pod with a single ready container:
kubectl -n teleport get podsNAME READY STATUS RESTARTS AGEteleport-kube-agent-0 1/1 Running 0 32s
The Database Service will attempt to enable IAM authentication and configure IAM access policies for the registered databases. Keep in mind that AWS IAM changes may not propagate immediately and can take a few minutes to come into effect.
Step 5/6. Create a database IAM user
Database users must allow IAM authentication in order to be used with Database
Access for RDS. See below how to enable it for the user alice
on your database
engine. In the next step, we will authenticate to the database as the alice
user via the user's Teleport account.
PostgreSQL users must have a rds_iam
role:
CREATE USER alice;
GRANT rds_iam TO alice;
MySQL and MariaDB users must have the RDS authentication plugin enabled:
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:
GRANT ALL ON `%`.* TO 'alice'@'%';
See Creating a database account using IAM authentication for more information.
Step 6/6. 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:
tsh login --proxy=example.teleport.sh:443 --user=alicetsh db lsName Description Labels
------------------------------ --------------------------------------------- --------
postgres-rds RDS instance in us-west-1 ...
aurora-mysql Aurora cluster in us-west-1 ...
aurora-mysql-custom-myendpoint Aurora cluster in us-west-1 (custom endpoint) ...
aurora-mysql-reader Aurora cluster in us-west-1 (reader endpoint) ...
Primary, reader, and custom endpoints of Aurora clusters have names with the
format
<cluster-id>
, <cluster-id>-reader
, and
<cluster-id>-custom-<endpoint-name>
respectively.
You can override the <cluster-id>
part of the name with the
TeleportDatabaseName
AWS tag.
Retrieve credentials for a database and connect to it as the alice
user,
assigning postgres-rds to the name of a database resource listed
by tsh db ls
:
tsh db connect postgres-rds --db-user=alice
You can optionally specify the database name to use by default when connecting to the database instance:
tsh db connect --db-user=postgres --db-name=postgres postgres-rds
The appropriate database command-line client (psql
, mysql
, mariadb
) should be
available in PATH
in order to be able to connect.
Log out of the database and remove credentials:
tsh db logout postgres-rds
Troubleshooting
Certificate error
If your tsh db connect
error includes the following text, you likely have an RDS database created before July 28, 2020, which presents an X.509 certificate that is incompatible with Teleport:
x509: certificate relies on legacy Common Name field, use SANs instead
AWS provides instructions to rotate your SSL/TLS certificate.
No credential providers error
If you see the error NoCredentialProviders: no valid providers in chain
in Database Service logs then Teleport
is not detecting the required credentials to connect via AWS IAM permissions. Check whether
the credentials or security role has been applied in the machine running the Teleport Database Service.
Timeout errors
The Teleport Database Service needs connectivity to your database endpoints. That may require
enabling inbound traffic on the database from the Database Service on the same VPC or routing rules from another VPC. Using the nc
program you can verify connections to databases:
nc -zv postgres-instance-1.sadas.us-east-1.rds.amazonaws.com 5432Connection to postgres-instance-1.sadas.us-east-1.rds.amazonaws.com (172.31.24.172) 5432 port [tcp/postgresql] succeeded!
Maximum policy size exceeded errors
Due to IAM and STS character limits, you may encounter one of the following errors in the Database Service logs when large numbers of databases are registered:
LimitExceeded: Maximum policy size of 2048 bytes exceeded for userĀ <iam-user>
LimitExceeded: Maximum policy size of 10240 bytes exceeded for role <iam-role>
For reference, a user policy can maintain permissions for approximately 6 Redshift databases, or 20 RDS databases due to the IAM policy character limits. A role policy can maintain permissions for approximately 30 Redshift databases, or 100 RDS databases.
To get around this limit, try using one or a combination of the following methods:
You can reduce the policy size by separating them into multiple IAM roles. Use
assume_role_arn
to specify different IAM roles for accessing the databases:
You can specify assume_role_arn
in the AWS matchers of Discovery Service's
configuration:
discovery_service:
enabled: "yes"
aws:
- types: ["rds"]
regions: ["us-west-1", "us-west-2"]
assume_role_arn: "arn:aws:iam::123456789012:role/example-role-rds-env-prod-discovery"
tags:
"env": "prod"
- types: ["redshift", "redshift-serverless"]
regions: ["us-west-2"]
assume_role_arn: "arn:aws:iam::123456789012:role/example-role-redshift-env-dev"
tags:
"env": "dev"
The Discovery Service will use the IAM roles specified in assume_role_arn
for discovery, and by default the Database Service will use the same IAM
roles for authentication.
However, you can also overwrite the IAM roles for authentication by Database Service if you wish to use different roles:
db_service:
enabled: "yes"
resources:
# Matches us-west-1 env=prod RDS databases from Discovery Service, and
# overwrites assume_role_arn.
- labels:
"env": "prod"
"region": "us-west-1"
aws:
assume_role_arn: "arn:aws:iam::123456789012:role/example-role-rds-env-prod-us-west-1-access"
# Matches us-west-2 env=prod RDS databases from Discovery Service, and
# overwrites assume_role_arn.
- labels:
"env": "prod"
"region": "us-west-2"
aws:
assume_role_arn: "arn:aws:iam::123456789012:role/example-role-rds-env-prod-us-west-2-access"
# Matches env=dev Redshift databases from Discovery Service and inherits
# "arn:aws:iam::123456789012:role/example-role-redshift-env-dev"
- labels:
"env": "dev"
Teleport generates certain labels derived from the cloud resource attributes during discovery. See Auto-Discovery labels /labels/#auto-discovery) for more details.
Create or print the required IAM policies with the following commands and attach them to the respective IAM roles:
teleport db configure aws create-iam --types redshift,redshift-serverless --name teleport-redshift-accessteleport db configure aws print-iam --types redshift,redshift-serverless
Refer to the command usage for a complete list of database types supported by
the --types
option.
You can specify assume_role_arn
in the AWS matchers of Database Service's
configuration:
db_service:
enabled: "yes"
aws:
- types: ["rds"]
regions: ["us-west-1", "us-west-2"]
assume_role_arn: "arn:aws:iam::123456789012:role/example-role-rds-env-prod"
tags:
"env": "prod"
- types: ["redshift", "redshift-serverless"]
regions: ["us-west-2"]
assume_role_arn: "arn:aws:iam::123456789012:role/example-role-redshift-env-dev"
tags:
"env": "dev"
The Database Service will use the IAM roles specified assume_role_arn
for
both discovery and authentication.
To bootstrap IAM permissions, run the bootstrap command for each assume_role_arn
:
teleport db configure bootstrap \ -c /etc/teleport.yaml \ --policy-name teleport-policy-rds-env-prod \ --attach-to-role "arn:aws:iam::123456789012:role/example-role-rds-env-prod"
You can specify aws.assume_role_arn
when defining databases in Database
Service's configuration:
db_service:
enabled: "yes"
databases:
- name: "rds-postgres"
protocol: "postgres"
uri: "rds-postgres.abcdef012345.us-west-1.rds.amazonaws.com:5432"
aws:
assume_role_arn: "arn:aws:iam::123456789012:role/example-rds-access-role"
To bootstrap IAM permissions, run the bootstrap command for each assume_role_arn
:
teleport db configure bootstrap \ -c /etc/teleport.yaml \ --policy-name teleport-policy-rds-access \ --attach-to-role "arn:aws:iam::123456789012:role/example-rds-access-role"
You can specify aws.assume_role_arn
when defining databases:
kind: db
version: v3
metadata:
name: "rds-postgres"
labels:
env: "dev"
spec:
protocol: "postgres"
uri: "rds-postgres.abcdef012345.us-west-1.rds.amazonaws.com:5432"
aws:
assume_role_arn: "arn:aws:iam::123456789012:role/example-rds-access-role"
Alternatively, you can overwrite the IAM roles for authentication by Database Service:
db_service:
enabled: "yes"
resources:
# Matches env=dev databases and overwrites assume_role_arn.
- labels:
"env": "dev"
aws:
assume_role_arn: "arn:aws:iam::123456789012:role/example-env-dev-access"
# Matches env=prod database, and use the assume_role_arn in the database's
# definition or use the host IAM identity if assume_role_arn is empty.
- labels:
"env": "prod"
Create or print the required IAM policies with the following commands and attach them to the respective IAM roles:
teleport db configure aws create-iam --types rds --name teleport-rds-accessteleport db configure aws print-iam --types rds
Refer to the command usage for a complete list of database types supported by
the --types
option.
The IAM roles specified in assume_role_arn
must
trust
the IAM identity of the host running the Database Service.
The assume_role_arn
is not limited to the same AWS account so you can also
use this feature for AWS Cross-Account
Access.
You can manually manage IAM policies for database connections instead of relying on the Database Service to update them.
For example, you can limit the character size by attaching a policy with a wildcard "*" for "Resource":
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "rds-db:connect",
"Resource": "*"
}
]
}
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "redshift:GetClusterCredentials",
"Resource": "*"
}
]
}
You can safely remove the inline policy created by the Database Service and the
IAM permissions for the Database Service to Get/Put/Delete
the user or role
policy.
You can deploy the Database Service in a highly available (HA) configuration where databases can be sharded to separate Database Services with different IAM roles.
IAM users have a lower character limit compared to IAM roles. If the limit is exceeded for a user policy, it is recommended to use IAM roles for the Database Service instead.
Next steps
- Learn how to restrict access to certain users and databases.
- Learn more about dynamic database registration.
- View the High Availability (HA) guide.
- See the YAML configuration reference for updating dynamic resource matchers or static database definitions.
- Take a look at the full CLI reference.