diff --git a/docs/config.json b/docs/config.json index 09a5c92b7556c..456cdb0969b90 100644 --- a/docs/config.json +++ b/docs/config.json @@ -817,6 +817,10 @@ "title": "AWS Redshift", "slug": "/database-access/guides/postgres-redshift/" }, + { + "title": "AWS Redshift Serverless", + "slug": "/database-access/guides/redshift-serverless/" + }, { "title": "Azure Cache for Redis", "slug": "/database-access/guides/azure-redis/" diff --git a/docs/img/database-access/guides/redshift_cloud_serverless.png b/docs/img/database-access/guides/redshift_cloud_serverless.png new file mode 100644 index 0000000000000..c1a4ed2002441 Binary files /dev/null and b/docs/img/database-access/guides/redshift_cloud_serverless.png differ diff --git a/docs/img/database-access/guides/redshift_selfhosted_serverless.png b/docs/img/database-access/guides/redshift_selfhosted_serverless.png new file mode 100644 index 0000000000000..fba52f9f6e5d4 Binary files /dev/null and b/docs/img/database-access/guides/redshift_selfhosted_serverless.png differ diff --git a/docs/pages/database-access/guides/redshift-serverless.mdx b/docs/pages/database-access/guides/redshift-serverless.mdx new file mode 100644 index 0000000000000..c950877ba20d5 --- /dev/null +++ b/docs/pages/database-access/guides/redshift-serverless.mdx @@ -0,0 +1,375 @@ +--- +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. + + +![Teleport Database Access Redshift Self-Hosted](../../../img/database-access/guides/redshift_selfhosted_serverless.png) + + +![Teleport Database Access Redshift Cloud](../../../img/database-access/guides/redshift_cloud_serverless.png) + + +## 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 + + +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. + + +```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' # only the role name, do not specify the full AWS ARN +``` + +- The value of `db_users` corresponds to the IAM role created in the previous step. +- 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`. + + +Use `--aws-tags =,=` 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](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. + + +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`. + +```code +$ 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: + +```code +$ teleport db configure bootstrap -c /etc/teleport.yaml --manual +``` + + + + +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: + + + + +```code +$ sudo systemctl start teleport +``` + + + + +```code +$ sudo teleport install systemd --output=/etc/systemd/system/teleport.service; +$ sudo systemctl enable teleport +$ sudo 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: + +```code +$ tsh login --proxy=mytenant.teleport.sh --user=alice +$ tsh db ls +Name 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: + +```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). diff --git a/docs/pages/includes/database-access/guides.mdx b/docs/pages/includes/database-access/guides.mdx index c4347aebd1ced..4c4f8e9d35730 100644 --- a/docs/pages/includes/database-access/guides.mdx +++ b/docs/pages/includes/database-access/guides.mdx @@ -5,6 +5,7 @@ - [AWS ElastiCache & MemoryDB](../../database-access/guides/redis-aws.mdx): Connect AWS ElastiCache or AWS MemoryDB for Redis database. - [AWS RDS & Aurora](../../database-access/guides/rds.mdx): Connect AWS RDS or Aurora PostgreSQL, MariaDB or MySQL database. - [AWS Redshift](../../database-access/guides/postgres-redshift.mdx): Connect AWS Redshift database. +- [AWS Redshift Serverless](../../database-access/guides/redshift-serverless.mdx): Connect to AWS Redshift serverless. - [AWS Keyspaces (Apache Cassandra)](../../database-access/guides/aws-cassandra-keyspaces.mdx): Connect to an AWS Keyspaces database. - [Azure PostgreSQL & MySQL](../../database-access/guides/azure-postgres-mysql.mdx): Connect Azure PostgreSQL or MySQL. - [Azure Cache for Redis](../../database-access/guides/azure-redis.mdx): Connect Azure Cache for Redis.