mirror of
https://github.com/gravitational/teleport.git
synced 2026-10-12 02:15:01 +00:00
Paul Gottschling
36fc5226f2
We are standardizing docs guides to add a page_type frontmatter field, with values for how-to guides, references, etc. We can then use this field to apply linting rules that ensure each guide type follows type-specific docs site conventions. The first convention is that each docs page must have an outcome statement, the structure of which depends on the guide's type. Human and AI agent readers can determine from the outcome statement whether to continue reading the guide or not. This change applies a `page_type` frontmatter field to 46 guides in the `enroll-resources` section of the docs. Most of these guides already include the expected outcome statement. For those that do not, this change adds one: - Automatic user provisioning introduction partial - Host user creation - Encrypted session recording guide - ClickHouse guide (rewording the existing outcome statement to match the standard structure we are rolling out). - Automatic session recording key rotation - Manual session recording key rotation - macOS launchd guide
207 lines
6.6 KiB
Plaintext
207 lines
6.6 KiB
Plaintext
---
|
|
title: Database Access with Amazon Redshift
|
|
sidebar_label: Redshift
|
|
description: How to configure Teleport database access with Amazon Redshift.
|
|
videoBanner: UFhT52d5bYg
|
|
tags:
|
|
- how-to
|
|
- zero-trust
|
|
- infrastructure-identity
|
|
- aws
|
|
page_type: how-to
|
|
---
|
|
|
|
(!docs/pages/includes/database-access/db-introduction.mdx dbType="Amazon Redshift" dbConfigure="with IAM authentication"!)
|
|
|
|
## How it works
|
|
|
|
(!docs/pages/includes/database-access/how-it-works/iam.mdx db="Amazon Redshift" cloud="AWS"!)
|
|
|
|
<Tabs>
|
|
<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">
|
|
|
|
</TabItem>
|
|
<TabItem scope={["cloud"]} label="Teleport Enterprise Cloud">
|
|
|
|
</TabItem>
|
|
|
|
</Tabs>
|
|
|
|
(!docs/pages/includes/database-access/auto-discovery-tip.mdx dbType="Amazon Redshift cluster" providerType="AWS"!)
|
|
|
|
## Prerequisites
|
|
|
|
(!docs/pages/includes/edition-prereqs-tabs.mdx!)
|
|
|
|
- AWS account with a Redshift cluster and permissions to create and attach IAM
|
|
policies.
|
|
- Command-line client `psql` installed and added to your system's `PATH` environment variable.
|
|
- A host, e.g., an EC2 instance, where you will run the Teleport Database
|
|
Service.
|
|
- (!docs/pages/includes/tctl.mdx!)
|
|
|
|
## Step 1/5. Create a Teleport user
|
|
|
|
(!docs/pages/includes/database-access/create-user.mdx!)
|
|
|
|
## Step 2/5. Create a Database Service configuration
|
|
|
|
(!docs/pages/includes/tctl-token.mdx serviceName="Database" tokenType="db" tokenFile="/tmp/token"!)
|
|
|
|
(!docs/pages/includes/database-access/alternative-methods-join.mdx!)
|
|
|
|
(!docs/pages/includes/install-linux.mdx!)
|
|
|
|
On the node that is running the Database Service, create a configuration file.
|
|
Assign `CLUSTER_URI` to the domain name and port of the cluster:
|
|
|
|
<Tabs>
|
|
<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">
|
|
|
|
```code
|
|
$ sudo teleport db configure create \
|
|
-o file \
|
|
--name="redshift-postgres" \
|
|
--proxy=teleport.example.com:443 \
|
|
--protocol=postgres \
|
|
--token=/tmp/token \
|
|
--uri=${CLUSTER_URI?}
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem scope={["cloud"]} label="Teleport Enterprise Cloud">
|
|
|
|
```code
|
|
$ sudo teleport db configure create \
|
|
-o file \
|
|
--name="redshift-postgres" \
|
|
--proxy=mytenant.teleport.sh:443 \
|
|
--protocol=postgres \
|
|
--token=/tmp/token \
|
|
--uri=${CLUSTER_URI?}
|
|
```
|
|
|
|
</TabItem>
|
|
|
|
</Tabs>
|
|
|
|
The command will generate a Database Service configuration to proxy your AWS
|
|
Redshift cluster and place it at the `/etc/teleport.yaml` location.
|
|
|
|
## Step 3/5. Configure IAM permissions for the Database Service
|
|
|
|
(!docs/pages/includes/database-access/create-iam-role-step-description.mdx accessFor="Redshift databases" !)
|
|
|
|
### 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/redshift/access-policy.mdx dbUserRole="redshift-user-role" !)
|
|
|
|
## Step 4/5. Start the Database Service
|
|
|
|
(!docs/pages/includes/start-teleport.mdx service="the Database Service"!)
|
|
|
|
The Database Service will proxy the Amazon Redshift cluster with the ID you
|
|
specified earlier. 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
|
|
|
|
<Tabs>
|
|
<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">
|
|
|
|
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.
|
|
|
|
```code
|
|
$ tsh login --proxy=teleport.example.com --user=alice
|
|
$ tsh db ls
|
|
# Name Description Labels
|
|
# ----------- ------------------------------ --------
|
|
# my-redshift ...
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem scope={["cloud"]} label="Teleport Enterprise Cloud">
|
|
|
|
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 Cloud
|
|
tenant.
|
|
|
|
```code
|
|
$ tsh login --proxy=mytenant.teleport.sh --user=alice
|
|
$ tsh db ls
|
|
# Name Description Labels
|
|
# ----------- ------------------------------ --------
|
|
# my-redshift ...
|
|
```
|
|
|
|
</TabItem>
|
|
|
|
</Tabs>
|
|
|
|
To retrieve credentials for a database and connect to it:
|
|
|
|
```code
|
|
$ tsh db connect --db-user=alice --db-name=dev my-redshift
|
|
```
|
|
|
|
<Admonition type="note" title="Database users must exist">
|
|
Teleport does not currently use the auto-create option when generating
|
|
tokens for Redshift databases. Users must exist in the database.
|
|
</Admonition>
|
|
|
|
(!docs/pages/includes/database-access/proxy-db-tunnel.mdx db="my-redshift" dbArgs="--db-user=alice --db-name=dev"!)
|
|
|
|
(!docs/pages/includes/database-access/db-access-webui-ad.mdx dbType="PostgreSQL"!)
|
|
|
|
To log out of the database and remove credentials:
|
|
|
|
```code
|
|
$ tsh db logout my-redshift
|
|
```
|
|
|
|
## Authenticate Redshift with as an IAM role
|
|
|
|
Amazon Redshift supports two methods of IAM-based authentication, and Teleport
|
|
is compatible with both.
|
|
|
|
**First method: Authenticate as a Database User (Default)**
|
|
|
|
In this method, the Teleport Database Service generates a temporary IAM
|
|
authentication token for an existing database user in Redshift. This user must
|
|
already exist in the Redshift database. Teleport uses this method by default.
|
|
|
|
**Second method: Authenticate as an IAM Role**
|
|
|
|
In this alternative method, the Teleport Database Service assumes an AWS IAM
|
|
role to authenticate to Redshift. Redshift maps the IAM role to a database user
|
|
and automatically creates that user if it doesn't already exist. If you use this
|
|
method, you must first create an AWS IAM role that grants access to the Redshift
|
|
database.
|
|
|
|
(!docs/pages/includes/database-access/reference/aws-iam/redshift/role-as-user-policy.mdx dbUserRole="redshift-user-role"!)
|
|
|
|
## Troubleshooting
|
|
|
|
(!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 PIDQuery="SELECT pid,starttime,duration,trim(user_name) AS user,trim(query) AS query FROM stv_recents WHERE status = 'Running';"!)
|
|
|
|
(!docs/pages/includes/database-access/psql-ssl-syscall-error.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 Amazon Redshift.
|
|
|
|
(!docs/pages/includes/database-access/guides-next-steps.mdx!)
|