Skip to content

Commit

Permalink
Update database guides with database configurator. (#10451) (#10995)
Browse files Browse the repository at this point in the history 
* docs: update database guides to use configurator

* Apply suggestions from code review

Co-authored-by: Roman Tkachenko <[email protected]>

* docs(database): add auto-discovery IAM policies reference

* docs(database): update with code review suggestions

* docs(database): update with review suggestions

* Apply suggestions from code review

Co-authored-by: Paul Gottschling <[email protected]>

* docs(database): remove H3 lines

* docs(database): update auto-discovery reference

* docs(database): update policy examples to be more restrictive

* Apply suggestions from code review

Co-authored-by: Paul Gottschling <[email protected]>

Co-authored-by: Roman Tkachenko <[email protected]>
Co-authored-by: Paul Gottschling <[email protected]>

Co-authored-by: Roman Tkachenko <[email protected]>
Co-authored-by: Paul Gottschling <[email protected]>
  • Loading branch information
@gabrielcorado @r0mant @ptgott
3 people authored Mar 9, 2022
1 parent 81f2a9e commit 4ba86c2
Show file tree
Hide file tree
Showing 9 changed files with 379 additions and 492 deletions.
53 changes: 11 additions & 42 deletions docs/pages/database-access/guides/mysql-self-hosted.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -131,48 +131,17 @@ tunnel.

### Start Database Service with Config File

Below is an example of a database service configuration file that proxies
a single self-hosted MySQL database:

```yaml
teleport:
# The data_dir should be a different location if running on the same
# machine as Teleport auth and proxy.
data_dir: /var/lib/teleport-db
nodename: teleport-db-instance
# Teleport invitation token used to join a cluster.
# can also be passed on start using --token flag
auth_token: /tmp/token
# Proxy address to connect to. Note that it has to be the proxy address
# because database service always connects to the cluster over reverse
# tunnel.
auth_servers:
- teleport.example.com:3080
db_service:
enabled: "yes"
# This section contains definitions of all databases proxied by this
# service, can contain multiple items.
databases:
# Name of the database proxy instance, used to reference in CLI.
- name: "example"
# Free-form description of the database proxy instance.
description: "Example MySQL"
# Database protocol.
protocol: "mysql"
# Database address, MySQL/MariaDB server endpoint in this case.
#
# Note: this URI's hostname must match the host name specified via --host
# flag to tctl auth sign command.
uri: "mysql.example.com:3306"
# Labels to assign to the database, used in RBAC.
static_labels:
env: dev
auth_service:
enabled: "no"
ssh_service:
enabled: "no"
proxy_service:
enabled: "no"
Generate a configuration file at `/etc/teleport.yaml` for the Database Service:

```code
$ teleport db configure create \
-o file \
--token=/tmp/token \
--proxy=teleport.example.com:3080 \
--name=test \
--protocol=mysql \
--uri=mysql.example.com:3306 \
--labels=env=dev
```

<Admonition
Expand Down
177 changes: 23 additions & 154 deletions docs/pages/database-access/guides/postgres-redshift.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,173 +12,42 @@ videoBanner: UFhT52d5bYg
- AWS account with a Redshift cluster and permissions to create and attach IAM
policies.

## Step 1/5. Install Teleport
## Step 1/6. Install Teleport

(!docs/pages/includes/database-access/start-auth-proxy.mdx!)

## Step 2/5. Create Teleport user
## Step 2/6. Create Teleport user

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

## Step 3/5. Configure IAM
## Step 3/6. Create database agent configuration

### Create an IAM policy for Teleport
(!docs/pages/includes/database-access/token.mdx!)

Create the Database Service configuration file:

```code
$ teleport db configure create \
-o file \
--proxy=teleport.example.com:3080 \
--token=/tmp/token \
--redshift-discovery=us-west-1
```

The command will generate a Database Service configuration with Redshift
database auto-discovery enabled on the `us-west-1` region and place it at the
`/etc/teleport.yaml` location.

## Step 4/6. Create an IAM policy for Teleport

Teleport needs AWS IAM permissions to be able to:

- Discover and register Redshift databases.
- Manage IAM user or IAM role policies.

Go to the [Policies](https://console.aws.amazon.com/iamv2/home#/policies) page
in the AWS Management Console and create a managed IAM policy for the database
agent.

The exact set of required permissions depends on the IAM identity your Teleport
database agent will be using (IAM user or IAM role).

<Tabs>
<TabItem label="IAM user">
Use this policy if your Teleport database agent runs as an IAM user (for
example, uses AWS credentials file).
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"redshift:DescribeClusters",
"iam:GetUserPolicy",
"iam:PutUserPolicy",
"iam:DeleteUserPolicy"
],
"Resource": "*"
}
]
}
```
</TabItem>
<TabItem label="IAM role">
Use this policy if your Teleport database agent runs as an IAM role (for
example, on an EC2 instance with attached IAM role).
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"redshift:DescribeClusters",
"iam:GetRolePolicy",
"iam:PutRolePolicy",
"iam:DeleteRolePolicy"
],
"Resource": "*"
}
]
}
```
</TabItem>
</Tabs>

### Create an IAM permission boundary for Teleport
Since Teleport will be managing its own IAM policies for access to Redshift
databases, you need to create a permission boundary to limit its effective
range of permissions.

Create another managed policy that will serve as a permission boundary on the
same [Policies](https://console.aws.amazon.com/iamv2/home#/policies) page of
the AWS Management Console.

In addition to the set of permissions you created above, the boundary should
also include `redshift:GetClusterCredentials`, which will grant your Teleport
agent the permission to generate temporary credentials to authenticate with
Redshift databases.

Similar to the permission polices you created above, the exact set of required
permissions for the permission boundary depends on the IAM identity your
Teleport database agent will be using (IAM user or IAM role).

<Tabs>
<TabItem label="IAM user">
Use this permission boundary if your Teleport database agent runs as an IAM
user (for example, uses AWS credentials file).
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"redshift:DescribeClusters",
"redshift:GetClusterCredentials",
"iam:GetUserPolicy",
"iam:PutUserPolicy",
"iam:DeleteUserPolicy"
],
"Resource": "*"
}
]
}
```
</TabItem>
<TabItem label="IAM role">
Use this permission boundary if your Teleport database agent runs as an IAM
role (for example, on an EC2 instance with attached IAM role).
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"redshift:DescribeClusters",
"redshift:GetClusterCredentials",
"iam:GetRolePolicy",
"iam:PutRolePolicy",
"iam:DeleteRolePolicy"
],
"Resource": "*"
}
]
}
```
</TabItem>
</Tabs>

### Attach the policy and boundary to an IAM identity
(!docs/pages/includes/database-access/attach-iam-policies.mdx!)

<Admonition type="note" title="Self-managed IAM">
If you prefer to self-manage IAM for your Redshift databases, see [AWS
reference](../reference/aws.mdx) for details.
</Admonition>

## Step 4/5. Start the database agent
(!docs/pages/includes/database-access/token.mdx!)

Create the database agent configuration e.g. in `/etc/teleport.yaml`:

```yaml
teleport:
data_dir: /var/lib/teleport
auth_token: /tmp/token
auth_servers:
- teleport.example.com:443 # Teleport proxy address to connect to
auth_service:
enabled: "no"
proxy_service:
enabled: "no"
db_service:
enabled: "yes"
aws: # Matchers for registering AWS-hosted databases.
- types: ["redshift"]
regions: ["us-west-1"] # AWS regions to fetch databases from
tags: # AWS database resource tags to match
"*": "*"
```
(!docs/pages/includes/database-access/aws-bootstrap.mdx!)

Start the database agent:
## Step 5/6. Start the database agent

```code
$ teleport start --config=/etc/teleport.yaml
Expand All @@ -195,7 +64,7 @@ may not propagate immediately and can take a few minutes to come into effect.
for more information.
</Admonition>

## Step 5/5. Connect
## Step 6/6. Connect

Once the database agent has started and joined the cluster, log in to see the
registered databases. Replace `--proxy` with the address of your Teleport Proxy Service,
Expand Down
48 changes: 11 additions & 37 deletions docs/pages/database-access/guides/postgres-self-hosted.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -111,43 +111,17 @@ tunnel.

### Start Database service with config file

Below is an example of a database service configuration file that proxies
a single self-hosted PostgreSQL database:

```yaml
teleport:
data_dir: /var/lib/teleport-db
nodename: test
# Proxy address to connect to. Note that it has to be the proxy address
# because database service always connects to the cluster over reverse
# tunnel.
auth_servers:
- teleport.example.com:3080
db_service:
enabled: "yes"
# This section contains definitions of all databases proxied by this
# service, can contain multiple items.
databases:
# Name of the database proxy instance, used to reference in CLI.
- name: "example"
# Free-form description of the database proxy instance.
description: "Example PostgreSQL"
# Database protocol.
protocol: "postgres"
# Database address, PostgreSQL server endpoint in this case.
#
# Note: this URI's hostname must match the host name specified via --host
# flag to tctl auth sign command.
uri: "postgres.example.com:5432"
# Labels to assign to the database, used in RBAC.
static_labels:
env: dev
auth_service:
enabled: "no"
ssh_service:
enabled: "no"
proxy_service:
enabled: "no"
Generate a configuration file at `/etc/teleport.yaml` for the Database Service:

```code
$ teleport db configure create \
-o file \
--token=/tmp/token \
--proxy=teleport.example.com:3080 \
--name=test \
--protocol=postgres \
--uri=postgres.example.com:5432 \
--labels=env=dev
```

<Admonition
Expand Down
Loading

0 comments on commit 4ba86c2

Please sign in to comment.