[Docs] Redshift Serverless Guide (#20168)

* init Redshift Serverless guide * Apply suggestions from code review Co-authored-by: STeve (Xin) Huang <[email protected]> * Update docs/pages/database-access/guides/redshift-serverless.mdx * update for review feedback * Apply suggestions from code review Co-authored-by: Paul Gottschling <[email protected]> * update based on review feedback * clarify ambiguous pronoun * Apply suggestions from code review Co-authored-by: Paul Gottschling <[email protected]> --------- Co-authored-by: STeve (Xin) Huang <[email protected]> Co-authored-by: Paul Gottschling <[email protected]>
gravitational · Feb 3, 2023 · a5909b0 · a5909b0
1 parent 6f9ad95
commit a5909b0
Show file tree

Hide file tree

Showing 5 changed files with 380 additions and 0 deletions.
diff --git 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
diff --git a/docs/img/database-access/guides/redshift_selfhosted_serverless.png b/docs/img/database-access/guides/redshift_selfhosted_serverless.png
diff --git a/docs/pages/database-access/guides/redshift-serverless.mdx 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.
+
+<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' # 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`.
+
+<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).
diff --git 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.