Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update database guides with database configurator. #10451

Merged
merged 12 commits into from
Mar 8, 2022
Merged

Update database guides with database configurator. #10451

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
0a08a01
docs: update database guides to use configurator
gabrielcorado Feb 18, 2022
d88bc3a
Apply suggestions from code review
gabrielcorado Feb 25, 2022
ffc3a65
docs(database): add auto-discovery IAM policies reference
gabrielcorado Feb 25, 2022
389cbed
docs(database): update with code review suggestions
gabrielcorado Feb 25, 2022
5066b54
docs(database): update with review suggestions
gabrielcorado Mar 2, 2022
09b7a7b
Apply suggestions from code review
gabrielcorado Mar 4, 2022
09ff2e0
docs(database): remove H3 lines
gabrielcorado Mar 4, 2022
766191d
docs(database): update auto-discovery reference
gabrielcorado Mar 4, 2022
4299386
docs(database): update policy examples to be more restrictive
gabrielcorado Mar 4, 2022
596f110
Merge branch 'master' into gabrielcorado/db-configurator-docs
gabrielcorado Mar 4, 2022
4c9a2c2
Apply suggestions from code review
gabrielcorado Mar 7, 2022
5601c99
Merge branch 'master' into gabrielcorado/db-configurator-docs
gabrielcorado Mar 8, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 11 additions & 42 deletions docs/pages/database-access/guides/mysql-self-hosted.mdx
View file
Open in desktop
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
Open in desktop
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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When are we using "Database Service" vs "database agent"? Are the two terms interchangeable?

Copy link
Contributor Author

@gabrielcorado gabrielcorado Mar 2, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure which one we should use or if we can use both. @r0mant, do you have any thoughts on which name is more appropriate?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On second thought, using "database agent" vs. "Database Service" is a docs-wide issue, so we can talk about it a separate issue so we don't block this PR.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I've been trying to standardize on "Database Service" or "Database Service agent" following @ptgott's lead.


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

Create the Database Service configuration file:

```code
gabrielcorado marked this conversation as resolved.
Show resolved Hide resolved
$ 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
Open in desktop
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