teleport/docs/pages/database-access/guides/redshift-serverless.mdx

---
title: Database Access with Redshift Serverless on AWS
description: How to configure Teleport Database Access with AWS Redshift Serverless.
---

This guide will help you to:

- Set up Teleport to access your AWS Redshift Serverless workgroups.
- Connect to your databases through Teleport.

<ScopedBlock scope={["oss", "enterprise"]}>
![Teleport Database Access Redshift Self-Hosted](../../../img/database-access/guides/redshift_selfhosted_serverless.png)
</ScopedBlock>
<ScopedBlock scope={["cloud"]}>
![Teleport Database Access Redshift Cloud](../../../img/database-access/guides/redshift_cloud_serverless.png)
</ScopedBlock>

## Prerequisites

- A pre-existing Teleport `(=teleport.version=)` cluster. If you don't already
  have Teleport running, see [How to Choose a Teleport Edition](../../choose-an-edition/introduction.mdx)
  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's `PATH` 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.
- (!docs/pages/includes/tctl.mdx!)

## Step 1/5. Create an IAM policy for Teleport

<Admonition type="note" title="Example Access Control">
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.
</Admonition>

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:

<Admonition type="tip">
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.
</Admonition>

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "iam:AttachRolePolicy",
                "iam:PutRolePermissionsBoundary"
            ],
            "Resource": [
                "arn:aws:iam::(=aws.aws_access_key=):role/teleport-redshift-serverless-node"
            ],
            "Effect": "Allow"
        },
        {
            "Action": [
                "iam:GetPolicy",
                "iam:CreatePolicy",
                "iam:TagPolicy",
                "iam:ListPolicyVersions",
                "iam:CreatePolicyVersion"
            ],
            "Resource": [
                "arn:aws:iam::(=aws.aws_access_key=):policy/DatabaseAccess",
                "arn:aws:iam::(=aws.aws_access_key=):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:

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Statement1",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::(=aws.aws_access_key=):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:

```json
{
    "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:

```json
{
...
      "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`:

```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,
  but `dev` 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:

```code
$ tctl create -f redshift-role.yaml
role 'redshift-serverless-access' has been created
```

(\!docs/pages/includes/add-role-to-user.mdx role="redshift-serverless-access" \!)

## Step 4/5. Install and start the Teleport Database Service

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

Install Teleport on the host where you will run the Teleport Database Service:

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

On the same host, create a Teleport configuration file:

```code
$ 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`.

<Admonition type="tip" title="Filter with AWS tags">
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`.
</Admonition>

### 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.

<Admonition type="note" title="AWS credentials">
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](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials)
for alternative methods of providing AWS credentials for non-EC2 nodes.
</Admonition>

Run one of the following commands on your Database Service node:

<Tabs>
<TabItem label="Automatic">

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`.

```code
$ teleport db configure bootstrap -c /etc/teleport.yaml
```

</TabItem>
<TabItem label="Manual">

Use this command to display required IAM policies which you will then create in your AWS console:

```code
$ teleport db configure bootstrap -c /etc/teleport.yaml --manual
```

</TabItem>
</Tabs>

See the full `bootstrap` command
[reference](../../database-access/reference/cli.mdx#teleport-db-configure-bootstrap)
for more information.

### Start the Database service

Run the following command on the Database Service node, depending on how you
installed Teleport:

<Tabs>
<TabItem label="Package Manager">

```code
$ sudo systemctl start teleport
```

</TabItem>
<TabItem label="TAR archive">

```code
$ sudo teleport install systemd --output=/etc/systemd/system/teleport.service;
$ sudo systemctl enable teleport
$ sudo systemctl start teleport
```

</TabItem>
</Tabs>

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:

```code
$ tsh login --proxy=mytenant.teleport.sh --user=alice
$ tsh db ls
Name        Description                    Labels
----------- ------------------------------ --------
my-redshift Redshift cluster in us-east-1  ...
```

<Admonition type="note" title="Note">

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.

</Admonition>

To connect to the Redshift Serverless instance:

```code
$ tsh db connect my-redshift --db-user=teleport-redshift-serverless-access --db-name=dev
psql (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:

```code
$ 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:

1. Connect to the Redshift Serverless workgroup as the admin user, and execute:

   ```sql
   CREATE USER "IAMR:teleport-redshift-serverless-access" WITH PASSWORD DISABLE;
   ```

2. Grant this user appropriate in-database permissions. For example:

   ```sql
   GRANT SELECT ON TABLE users  TO "IAMR:teleport-redshift-serverless-access";
   ```

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

## Next steps

- Learn more about [using IAM authentication to generate database user
  credentials](https://docs.aws.amazon.com/redshift/latest/mgmt/generating-user-credentials.html) for AWS Redshift.
- Learn how to [restrict access](../rbac.mdx) to certain users and databases.
- View the [High Availability (HA)](../guides/ha.mdx) guide.
- Take a look at the YAML configuration [reference](../reference/configuration.mdx).