
This guide will help you to:
- Set up Teleport to access your AWS Redshift Serverless workgroups.
- Connect to your databases through Teleport.

Prerequisites
- A pre-existing Teleport
12.1.1
cluster. If you don't already have Teleport running, see How to Choose a Teleport Edition to learn more about your options, and how to set up Teleport. - AWS account with a Redshift Serverless configuration and permissions to create and attach IAM policies.
- Command-line client
psql
installed and added to your system'sPATH
environment variable. - A host where you will run the Teleport Database Service. This guide assumes an EC2 instance, and provides a corresponding example of access control.
-
To connect to Teleport, log in to your cluster using
tsh
, then usetctl
remotely:tsh login --proxy=teleport.example.com [email protected]tctl statusCluster teleport.example.com
Version 12.1.1
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
You can run subsequent
tctl
commands in this guide on your local machine.For full privileges, you can also run
tctl
commands on your Auth Service host.To connect to Teleport, log in to your cluster using
tsh
, then usetctl
remotely:tsh login --proxy=myinstance.teleport.sh [email protected]tctl statusCluster myinstance.teleport.sh
Version 12.1.2
CA pin sha256:sha-hash-here
You must run subsequent
tctl
commands in this guide on your local machine.
Step 1/5. Create an IAM policy for Teleport
This guide provides an example configuration of IAM access roles as a model, and uses an EC2 instance to serve the Teleport Database Service. The level of access provided may not suit your needs, or may not fit your organization's access conventions. You should adjust the AWS IAM permissions to fit your needs.
Teleport needs AWS IAM permissions to be able to:
- Discover and register Redshift Serverless workgroups and their associated VPC endpoints.
- Manage IAM user or IAM role policies.
If you don't already have one, create a role to apply to the EC2 instance that
the Teleport Database Service will run on. This guide uses the example name
teleport-redshift-serverless-node
.
Under Trusted entity type choose "AWS service", and under Use case choose "EC2".
Create and attach a policy to the teleport-redshift-serverless-node
role to allow Teleport
to bootstrap access to AWS Redshift Serverless:
This policy is required for Automatic Teleport bootstrapping, documented below. You can optionally skip this policy, and select the "Manual" option when you reach step 4.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"iam:AttachRolePolicy",
"iam:PutRolePermissionsBoundary"
],
"Resource": [
"arn:aws:iam::abcd1234-this-is-an-example:role/teleport-redshift-serverless-node"
],
"Effect": "Allow"
},
{
"Action": [
"iam:GetPolicy",
"iam:CreatePolicy",
"iam:TagPolicy",
"iam:ListPolicyVersions",
"iam:CreatePolicyVersion"
],
"Resource": [
"arn:aws:iam::abcd1234-this-is-an-example:policy/DatabaseAccess",
"arn:aws:iam::abcd1234-this-is-an-example:policy/DatabaseAccessBoundary"
],
"Effect": "Allow"
}
]
}
Remember to replace the example AWS account ID. The policies defined in the
Resources
array will be created later in this guide.
Apply the teleport-redshift-serverless-node
role to the EC2 instance the
Teleport Database Service will be installed in.
Step 2/5. Create an IAM Role for user access
Create an AWS IAM role to provide user access to Redshift Serverless. This role
will be granted to Teleport users via a corresponding Teleport role. In this guide
we will use the example name teleport-redshift-serverless-access
.
Under Trusted entity type choose "Custom trust policy". Edit the trust policy to allow the IAM role generated in the previous step to assume this role, so that the Teleport node can use the permissions granted by this role to access databases:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Statement1",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::abcd1234-this-is-an-example:role/teleport-redshift-serverless-node",
"Service": "ec2.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
Remember to replace the example AWS account ID.
Create and apply a permission policy to allow access to Redshift Serverless. This policy can allow access to all instances:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "redshift-serverless:GetCredentials",
"Resource": "*"
}
]
}
Or you can restrict the Resource
line to a specific Redshift Serverless workgroup:
{
...
"Resource": "arn:aws:redshift-serverless:us-west-2:1234567890:workgroup/some-workgroup-id"
...
}
Step 3/5. Create a Teleport role for Redshift Serverless access
On your workstation logged in to your Teleport cluster with tsh
, define a new
role to provide access to Redshift Serverless. Our example file is
redshift-role.yaml
:
version: v5
kind: role
metadata:
name: redshift-serverless-access
spec:
allow:
db_labels:
'*': '*'
db_names:
- dev
db_users:
- 'teleport-redshift-serverless-access'
- The value of
db_users
corresponds to the IAM role created in the previous step. You can provide either the role name or the full AWS ARN of the IAM role. - The value(s) for
db_names
will depend on your Redshift Serverless configuration, butdev
is the default name applied by AWS. You can also provide*
to grant access to all instances.
Save this file and apply it to your Teleport cluster:
tctl create -f redshift-role.yamlrole 'redshift-serverless-access' has been created
Assign the redshift-serverless-access
role to your Teleport user by running the following
commands, depending on whether you authenticate as a local Teleport user or via
the github
, saml
, or oidc
authentication connectors:
Retrieve your local user's configuration resource:
tctl get users/$(tsh status -f json | jq -r '.active.username') > out.yaml
Edit out.yaml
, adding redshift-serverless-access
to the list of existing roles:
roles:
- access
- auditor
- editor
+ - redshift-serverless-access
Apply your changes:
tctl create -f out.yaml
Retrieve your github
configuration resource:
tctl get github/github --with-secrets > github.yaml
Edit github.yaml
, adding redshift-serverless-access
to the
teams_to_roles
section. The team you will map to this role will depend on how
you have designed your organization's RBAC, but it should be the smallest team
possible within your organization. This team must also include your user.
Here is an example:
teams_to_roles:
- organization: octocats
team: admins
roles:
- access
+ - redshift-serverless-access
Apply your changes:
tctl create -f github.yaml
Note the --with-secrets
flag in the tctl get
command. This adds the value of
spec.signing_key_pair.private_key
to saml.yaml
. This is a sensitive value,
so take precautions when creating this file and remove it after updating the resource.
Retrieve your saml
configuration resource:
tctl get --with-secrets saml/mysaml > saml.yaml
Edit saml.yaml
, adding redshift-serverless-access
to the
attributes_to_roles
section. The attribute you will map to this role will
depend on how you have designed your organization's RBAC, but it should be the
smallest group possible within your organization. This group must also include
your user.
Here is an example:
attributes_to_roles:
- name: "groups"
value: "my-group"
roles:
- access
+ - redshift-serverless-access
Apply your changes:
tctl create -f saml.yaml
Note the --with-secrets
flag in the tctl get
command. This adds the value of
spec.signing_key_pair.private_key
to saml.yaml
. This is a sensitive value,
so take precautions when creating this file and remove it after updating the resource.
Retrieve your oidc
configuration resource:
tctl get oidc/myoidc --with-secrets > oidc.yaml
Edit oidc.yaml
, adding redshift-serverless-access
to the
claims_to_roles
section. The claim you will map to this role will depend on
how you have designed your organization's RBAC, but it should be the smallest
group possible within your organization. This group must also include your
user.
Here is an example:
claims_to_roles:
- name: "groups"
value: "my-group"
roles:
- access
+ - redshift-serverless-access
Apply your changes:
tctl create -f saml.yaml
Note the --with-secrets
flag in the tctl get
command. This adds the value of
spec.signing_key_pair.private_key
to saml.yaml
. This is a sensitive value,
so take precautions when creating this file and remove it after updating the resource.
Log out of your Teleport cluster and log in again to assume the new role.
Step 4/5. Install and start the Teleport Database Service
The Database Service requires a valid auth token to connect to the cluster. Generate
one by running the following command against your Teleport Auth Service and save
it in /tmp/token
on the node that will run the Database Service:
tctl tokens add --type=db
Install Teleport on the host where you will run the Teleport Database Service:
Use the appropriate commands for your environment to install your package.
Teleport Edition
Add the Teleport repository to your repository list:
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 v12. You'll need to update this
file for each major release of Teleport.
Note: if using a fork of Debian or Ubuntu you may need to use '$ID_LIKE'
and the codename your distro was forked from instead of '$ID' and '$VERSION_CODENAME'.
Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L42-L67
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v12" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/nullsudo apt-get updatesudo apt-get install teleport
Source variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for v12. You'll need to update this
file for each major release of Teleport.
Note: if using a fork of RHEL/CentOS or Amazon Linux you may need to use '$ID_LIKE'
and the codename your distro was forked from instead of '$ID'
Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L133-L153
sudo yum-config-manager --add-repo $(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v12/teleport.repo")sudo yum install teleportTip: 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
Optional: Use DNF on newer distributions
$ sudo dnf config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo
$ sudo dnf install teleport
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-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gzshasum -a 256 teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gzVerify that the checksums match
tar -xvf teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gzcd teleportsudo ./install
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.
After Downloading the .deb
file for your system architecture, install it with
dpkg
. The example below assumes the root
user:
dpkg -i ~/Downloads/teleport-ent_12.1.1_$SYSTEM-ARCH.debSelecting previously unselected package teleport-ent.
(Reading database ... 30810 files and directories currently installed.)
Preparing to unpack teleport-ent_12.1.1_$SYSTEM_ARCH.deb ...
Unpacking teleport-ent 12.1.1 ...
Setting up teleport-ent 12.1.1 ...
After Downloading the .rpm
file for your system architecture, install it with rpm
:
rpm -i ~/Downloads/teleport-ent-12.1.1.$SYSTEM-ARCH.rpmwarning: teleport-ent-12.1.1.$SYSTEM-ARCH.rpm: Header V4 RSA/SHA512 Signature, key ID 6282c411: NOKEY
curl https://get.gravitational.com/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gzshasum -a 256 teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v12.1.1-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-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gzshasum -a 256 teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gzcd teleport-entsudo ./install
Please use the latest version of Teleport Enterprise documentation.
On the same host, create a Teleport configuration file:
teleport db configure create \ -o file \ --proxy=teleport.example.com:443 \ --token=/tmp/token \ --redshift-serverless-discovery=us-west-1
- Replace
teleport.example.com
with your Teleport proxy URI or cloud tenant address (e.g.mytenant.teleport.sh
). - Provide the token from the previous step to the
--token
flag. - Update the value of
--redshift-serverless-discovery
to match your AWS region.
This command will generate a Database Service configuration with Redshift
Serverless auto-discovery enabled and place it at /etc/teleport.yaml
.
Use --aws-tags <key>=<value>,<key>=<value>
to only match Redshift Serverless
workgroups with specified AWS resource tags.
For example, if a workgroup has multiple VPC endpoints but only one of the VPC
endpoints will be accessed through Teleport, add the resource tag
teleport.dev/discovery
with value true
to the VPC endpoint, and then specify
--aws-tags teleport.dev/discovery=true
when running teleport db configure create
.
Bootstrap access to Redshift Serverless
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 the
IAM permissions we applied to the
teleport-redshift-serverless-node
role earlier. - In manual mode, Teleport will print required IAM policies. You can then create and attach them manually using the AWS management console.
AWS Credentials are only required if you’re running the command in "automatic"
mode. The command uses the default credential provider chain to find AWS
credentials. The steps in this guide provide AWS credentials to the node by
applying the teleport-redshift-serverless-node
role to the instance. See
Specifying Credentials
for alternative methods of providing AWS credentials for non-EC2 nodes.
Run one of the following commands on your Database Service node:
Use this command to bootstrap the permissions automatically when your Teleport
Database Service runs on a host with AWS credentials. Teleport will automatically
determine the available role/user, or you can specify one with --attach-to-role
or attach-to-user
.
teleport db configure bootstrap -c /etc/teleport.yaml
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
See the full bootstrap
command
reference
for more information.
Start the Database service
Run the following command on the Database Service node, depending on how you installed Teleport:
sudo systemctl start teleport
sudo teleport install systemd --output=/etc/systemd/system/teleport.service;sudo systemctl enable teleportsudo systemctl start teleport
The Database Service will discover all Redshift databases according to the configuration and register them in the cluster. The Database Service will also attempt to configure IAM access policies for the discovered databases. Keep in mind that AWS IAM changes may not propagate immediately and can take a few minutes to come into effect.
Step 5/5. Connect
Once the Database Service has started and joined the cluster, log in to see the
registered databases. Replace --proxy
with the address of your Teleport Proxy
Service or cloud tenant:
tsh login --proxy=mytenant.teleport.sh --user=alicetsh db lsName Description Labels
----------- ------------------------------ --------
my-redshift Redshift cluster in us-east-1 ...
You can override the database name by applying the teleport.dev/database_name
AWS tag to the resource. The value of the tag will be used as the database name.
To connect to the Redshift Serverless instance:
tsh db connect my-redshift --db-user=teleport-redshift-serverless-access --db-name=devpsql (15.1, server 8.0.2)
WARNING: psql major version 15, server major version 8.0.
Some psql features might not work.
SSL connection (protocol: TLSv1.3, cipher: TLS_CHACHA20_POLY1305_SHA256, compression: off)
Type "help" for help.
dev=>
To log out of the database and remove credentials:
tsh db logout my-redshift
Troubleshooting
User permission errors
The IAM role teleport-redshift-serverless-access
will be automatically mapped
as IAMR:teleport-redshift-serverless-access
inside the Redshift Serverless database.
Users (database admins) can optionally set up this database user's permissions prior to logging in as this new IAM role to avoid or resolve user permission issues:
-
Connect to the Redshift Serverless workgroup as the admin user, and execute:
CREATE USER "IAMR:teleport-redshift-serverless-access" WITH PASSWORD DISABLE;
-
Grant this user appropriate in-database permissions. For example:
GRANT SELECT ON TABLE users TO "IAMR:teleport-redshift-serverless-access";
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 5432
Connection to postgres-instance-1.sadas.us-east-1.rds.amazonaws.com (172.31.24.172) 5432 port [tcp/postgresql] succeeded!
Next steps
- Learn more about using IAM authentication to generate database user credentials for AWS Redshift.
- Learn how to restrict access to certain users and databases.
- View the High Availability (HA) guide.
- Take a look at the YAML configuration reference.