diff --git a/docs/pages/database-access/guides/mysql-self-hosted.mdx b/docs/pages/database-access/guides/mysql-self-hosted.mdx index d4a9788beb88b..bcc443cec092b 100644 --- a/docs/pages/database-access/guides/mysql-self-hosted.mdx +++ b/docs/pages/database-access/guides/mysql-self-hosted.mdx @@ -131,50 +131,25 @@ 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" +You can use the database configurator to generate your agent configuration file: + +```code +$ teleport db configure create \ + --token=/tmp/token \ + --proxy=teleport.example.com:3080 \ + --name=test \ + --protocol=mysql \ + --uri=mysql.example.com:3306 \ + --labels=env=dev ``` + + By default, the command outputs the configuration file to STDOUT. You can + change that by providing the `-o/—output` flag. For example, to save the + configuration file to `/etc/teleport.yaml`, run the command with the `-o file` + flag. + + - - 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": "*" - } - ] - } - ``` - - - 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": "*" - } - ] - } - ``` - - - -### 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). - - - - 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": "*" - } - ] - } - ``` - - - 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": "*" - } - ] - } - ``` - - - -### Attach the policy and boundary to an IAM identity -(!docs/pages/includes/database-access/attach-iam-policies.mdx!) - - - If you prefer to self-manage IAM for your Redshift databases, see [AWS - reference](../reference/aws.mdx) for details. - - -## 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 @@ -195,7 +62,7 @@ may not propagate immediately and can take a few minutes to come into effect. for more information. -## 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, diff --git a/docs/pages/database-access/guides/postgres-self-hosted.mdx b/docs/pages/database-access/guides/postgres-self-hosted.mdx index 162873d4190aa..2fae874d91665 100644 --- a/docs/pages/database-access/guides/postgres-self-hosted.mdx +++ b/docs/pages/database-access/guides/postgres-self-hosted.mdx @@ -111,45 +111,25 @@ 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" +You can use the database configurator to generate your agent configuration file: + +```code +$ teleport db configure create \ + --token=/tmp/token \ + --proxy=teleport.example.com:3080 \ + --name=test \ + --protocol=postgres \ + --uri=postgres.example.com:5432 \ + --labels=env=dev ``` + + By default, the command outputs the configuration file to STDOUT. You can + change that by providing the `-o/—output` flag. For example, to save the + configuration file to `/etc/teleport.yaml`, run the command with the `-o file` + flag. + + - - Use this policy if you're connecting to RDS instances and your Teleport - database agent runs as IAM user (for example, uses AWS credentials file). - ```json - { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "rds:DescribeDBInstances", - "rds:ModifyDBInstance", - "iam:GetUserPolicy", - "iam:PutUserPolicy", - "iam:DeleteUserPolicy" - ], - "Resource": "*" - } - ] - } - ``` - - - Use this policy if you're connecting to RDS instances and your Teleport - database agent runs as IAM role (for example, on an EC2 instance with - attached IAM role). - ```json - { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "rds:DescribeDBInstances", - "rds:ModifyDBInstance", - "iam:GetRolePolicy", - "iam:PutRolePolicy", - "iam:DeleteRolePolicy" - ], - "Resource": "*" - } - ] - } - ``` - - - Use this policy if you're connecting to Aurora clusters and your Teleport - database agent runs as IAM user (for example, uses AWS credentials file). - ```json - { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "rds:DescribeDBClusters", - "rds:ModifyDBCluster", - "iam:GetUserPolicy", - "iam:PutUserPolicy", - "iam:DeleteUserPolicy" - ], - "Resource": "*" - } - ] - } - ``` - - - Use this policy if you're connecting to Aurora clusters and your Teleport - database agent runs as IAM role (for example, on an EC2 instance with - attached IAM role). - ```json - { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "rds:DescribeDBClusters", - "rds:ModifyDBCluster", - "iam:GetRolePolicy", - "iam:PutRolePolicy", - "iam:DeleteRolePolicy" - ], - "Resource": "*" - } - ] - } - ``` - - - -### Create IAM permission boundary for Teleport +(!docs/pages/includes/database-access/token.mdx!) -Since Teleport will be managing its own IAM policies for access to RDS and -Aurora databases, you need to create a permission boundary to limit its -effective range of permissions. +Create the database agent configuration using the database configurator: -Create another managed policy that will serve as a permission boundary on the -same [Policies](https://console.aws.amazon.com/iamv2/home#/policies) page. +```code +$ teleport db configure create -o file --proxy=teleport.example.com:3080 --token=/tmp/token --rds-discovery=us-west-1 +``` -The boundary should have the same set of permissions as the IAM policy you -created above, plus `rds-db:connect`. +The command will generate a database agent configuration with RDS/Aurora +databases auto-discovery enabled on the `us-west-1` region and place it at the +`/etc/teleport.yaml` location. - - - Use this permission boundary policy if you're connecting to RDS instances and - your Teleport database agent runs as IAM user (for example, uses AWS - credentials file). - ```json - { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "rds:DescribeDBInstances", - "rds:ModifyDBInstance", - "iam:GetUserPolicy", - "iam:PutUserPolicy", - "iam:DeleteUserPolicy", - "rds-db:connect" - ], - "Resource": "*" - } - ] - } - ``` - - - Use this permission boundary policy if you're connecting to RDS instances and - your Teleport database agent runs as IAM role (for example, on an EC2 instance - with attached IAM role). - ```json - { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "rds:DescribeDBInstances", - "rds:ModifyDBInstance", - "iam:GetRolePolicy", - "iam:PutRolePolicy", - "iam:DeleteRolePolicy", - "rds-db:connect" - ], - "Resource": "*" - } - ] - } - ``` - - - Use this permission boundary policy if you're connecting to Aurora clusters - and your Teleport database agent runs as IAM user (for example, uses AWS - credentials file). - ```json - { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "rds:DescribeDBClusters", - "rds:ModifyDBCluster", - "iam:GetUserPolicy", - "iam:PutUserPolicy", - "iam:DeleteUserPolicy", - "rds-db:connect" - ], - "Resource": "*" - } - ] - } - ``` - - - Use this permission boundary policy if you're connecting to Aurora clusters - and your Teleport database agent runs as IAM role (for example, on an EC2 - instance with attached IAM role). - ```json - { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "rds:DescribeDBClusters", - "rds:ModifyDBCluster", - "iam:GetRolePolicy", - "iam:PutRolePolicy", - "iam:DeleteRolePolicy", - "rds-db:connect" - ], - "Resource": "*" - } - ] - } - ``` - - +## Step 4/7. Configure IAM -### Attach the policy and boundary to an IAM identity -(!docs/pages/includes/database-access/attach-iam-policies.mdx!) +### Create IAM policy for Teleport - - If you prefer to self-manage IAM for your RDS databases, take a look at - [AWS reference](../reference/aws.mdx) for details. - +Teleport needs AWS IAM permissions to be able to: -## Step 4/6. Start the database agent +- Discover and register RDS instances and Aurora clusters. +- Configure IAM authentication for them. -(!docs/pages/includes/database-access/token.mdx!) +(!docs/pages/includes/database-access/aws-bootstrap.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 proxy address to connect to. - # For Teleport Cloud users, this will resemble mytenant.teleport.sh - - teleport.example.com:3080 -auth_service: - enabled: "no" -proxy_service: - enabled: "no" -db_service: - enabled: "yes" - aws: - - types: ["rds"] - regions: ["us-west-1"] # AWS regions to fetch databases from - tags: # AWS database resource tags to match - "*": "*" -``` +## Step 5/7. Start database agent Start the database agent: @@ -299,12 +71,11 @@ 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. - The Teleport database agent uses the default credential provider chain to find AWS - credentials. See [Specifying Credentials](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials) - for more information. + Similar to the bootstrap command, the Teleport database agent uses the default + credential provider chain to find AWS credentials. See [Specifying Credentials](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials) for more information. -## Step 5/6. Create database IAM user +## Step 6/7. Create database IAM user Database users must allow IAM authentication in order to be used with Database Access for RDS. See below how to enable it for your database engine. @@ -337,7 +108,7 @@ Access for RDS. See below how to enable it for your database engine. See [Creating a database account using IAM authentication](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/UsingWithRDS.IAMDBAuth.DBAccounts.html) for more information. -## Step 6/6. Connect +## Step 7/7. Connect Once the database agent has started and joined the cluster, login to see the registered databases: diff --git a/docs/pages/database-access/reference/cli.mdx b/docs/pages/database-access/reference/cli.mdx index dc77a23ce3721..26dcb6d1b8489 100644 --- a/docs/pages/database-access/reference/cli.mdx +++ b/docs/pages/database-access/reference/cli.mdx @@ -38,6 +38,53 @@ $ teleport db start \ | `--gcp-project-id` | (Only for Cloud SQL) GCP Cloud SQL project identifier. | | `--gcp-instance-id` | (Only for Cloud SQL) GCP Cloud SQL instance identifier.| +## teleport db configure create + +Creates a sample Database Service configuration. + +```code +$ teleport db configure create --rds-discovery=us-west-1 --rds-discovery=us-west-2 +$ teleport db configure create \ + --token=/tmp/token \ + --proxy=proxy.example.com:3080 \ + --name=example \ + --protocol=postgres \ + --uri=postgres://postgres.example.com:5432 \ + --labels=env=prod +``` + +| Flag | Description | +| - | - | +| `--proxy` | Teleport proxy address to connect to [0.0.0.0:3080]. | +| `--token` | Invitation token to register with an auth server [none]. | +| `--rds-discovery` | List of AWS regions the agent will discover for RDS/Aurora instances. | +| `--redshift-discovery` | List of AWS regions the agent will discover for Redshift instances. | +| `--ca-pin` | CA pin to validate the auth server (can be repeated for multiple pins). | +| `--name` | Name of the proxied database. | +| `--protocol` | Proxied database protocol. Supported are: [postgres mysql mongodb cockroachdb redis sqlserver]. | +| `--uri` | Address the proxied database is reachable at. | +| `--labels` | Comma-separated list of labels for the database, for example env=dev,dept=it | +| `-o/--output` | Write to stdout with -o=stdout, default config file with -o=file or custom path with -o=file:///path | + +## teleport db configure bootstrap + +Bootstrap the necessary configuration for the database agent. It reads the provided agent configuration to determine what will be bootstrapped. + +```code +$ teleport db configure bootstrap -c /etc/teleport.yaml --attach-to-user TeleportUser +$ teleport db configure bootstrap -c /etc/teleport.yaml --attach-to-role TeleportRole +$ teleport db configure bootstrap -c /etc/teleport.yaml --manual +``` + +| Flag | Description | +| - | - | +| `-c/--config` | Path to a configuration file [/etc/teleport.yaml]. | +| `--manual` | When executed in "manual" mode, it will print the instructions to complete the configuration instead of applying them directly. | +| `--policy-name` | Name of the Teleport Database agent policy. Default: "DatabaseAccess" | +| `--confirm` | Do not prompt user and auto-confirm all actions. | +| `--attach-to-role` | Role name to attach policy to. Mutually exclusive with --attach-to-user. If none of the attach-to flags is provided, the command will try to attach the policy to the current user/role based on the credentials. | +| `--attach-to-user` | User name to attach policy to. Mutually exclusive with --attach-to-role. If none of the attach-to flags is provided, the command will try to attach the policy to the current user/role based on the credentials. | + ## tctl auth sign When invoked with a `--format=db` (or `--format=mongodb` for MongoDB) flag, diff --git a/docs/pages/includes/database-access/aws-bootstrap.mdx b/docs/pages/includes/database-access/aws-bootstrap.mdx new file mode 100644 index 0000000000000..3f4a1a2e085d2 --- /dev/null +++ b/docs/pages/includes/database-access/aws-bootstrap.mdx @@ -0,0 +1,54 @@ +The exact set of required permissions depends on whether you're connecting to +different AWS-hosted databases, as well as the IAM identity your Teleport +database agent will be using (user or role). The database bootstrap command +generates custom AWS policies based on your configuration. Bootstrap can be +performed in two modes: +- Automatic: Generates and creates IAM policy and policy boundary and attaches + to provided target (user or role). In this command, the command requires AWS + credentials set to identity with enough permissions; +- Manual: Generates IAM policy and boundary and prints to STDOUT. You then can + add them to your AWS account manually (for instance, 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. See [Specifying Credentials](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials) for more information. + + + + + Use this command if you’re bootstrapping the permissions automatically and + your Teleport database agent runs as an IAM user (for example, uses AWS + credentials file). + + ```code + $ teleport db configure bootstrap -c /etc/teleport.yaml --attach-to-user TeleportUser + ``` + + + + Use this command if you’re bootstrapping the permissions automatically and + your Teleport database agent runs as an IAM role (for example, on an EC2 + instance with attached IAM role). + + ```code + $ teleport db configure bootstrap -c /etc/teleport.yaml --attach-to-role TeleportRole + ``` + + + + Use this command if you’re bootstrapping the permissions manually, and attach + the generated permissions to your target (user or role). + + ```code + $ teleport db configure bootstrap -c /etc/teleport.yaml --manual + ``` + + + + + The bootstrap command support other customizations, such as changing the IAM + policy name (`--policy-name`). For more options, check out the [command + reference page.](../../database-access/reference/cli.mdx#teleport-db-configure-bootstrap) + diff --git a/docs/pages/includes/database-access/guides-next-steps.mdx b/docs/pages/includes/database-access/guides-next-steps.mdx index 08a15db2a8e8a..d35299a6bda49 100644 --- a/docs/pages/includes/database-access/guides-next-steps.mdx +++ b/docs/pages/includes/database-access/guides-next-steps.mdx @@ -1,3 +1,4 @@ - Learn how to [restrict access](../../database-access/rbac.mdx) to certain users and databases. - View [High Availability (HA)](../../database-access/guides/ha.mdx) guide. - Take a look at YAML configuration [reference](../../database-access/reference/configuration.mdx). +- See full configuration and CLI [reference](../../database-access/reference/cli.mdx). diff --git a/docs/pages/kubernetes-access/helm/reference.mdx b/docs/pages/kubernetes-access/helm/reference.mdx index 96e3192058fc5..f49999fb097da 100644 --- a/docs/pages/kubernetes-access/helm/reference.mdx +++ b/docs/pages/kubernetes-access/helm/reference.mdx @@ -1487,7 +1487,7 @@ You can specify multiple apps by adding additional list elements. - For AWS database auto-discovery to work, your agent pods will need to use a role which has appropriate IAM permissions as per the [database documentation](../../database-access/guides/rds.mdx#step-36-configure-iam). + For AWS database auto-discovery to work, your agent pods will need to use a role which has appropriate IAM permissions as per the [database documentation](../../database-access/guides/rds.mdx#step-47-configure-iam). After configuring a role, you can use an `eks.amazonaws.com/role-arn` annotation with the `annotations.serviceAccount` value to associate it with the service account and grant permissions: