-
Notifications
You must be signed in to change notification settings - Fork 1.8k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* move AWS database discovery guide into subsection * write the overview for database discovery * generalize step description partial by service * split and generalize discovery troubleshooting * update AWS db discovery guide title * use step description partial in database discovery * add db svc troubleshooting partial for discovery
- Loading branch information
1 parent
d227ea7
commit 02d9ff3
Showing
15 changed files
with
508 additions
and
219 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,181 @@ | ||
| --- | ||
| title: AWS Database Discovery | ||
| description: How to configure Teleport to auto-discover AWS databases. | ||
| --- | ||
|
|
||
| Teleport can be configured to discover AWS databases automatically and register | ||
| them with your Teleport cluster. | ||
|
|
||
| (!docs/pages/includes/discovery/step-description.mdx serviceName="Database" resourceDesc="database" resourceKind="db"!) | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| (!docs/pages/includes/edition-prereqs-tabs.mdx!) | ||
|
|
||
| - An AWS account with permissions to create and attach IAM policies. | ||
| - One or more database servers hosted by AWS database services. | ||
| - A host to run the Teleport Discovery Service. | ||
|
|
||
| ## Step 1/4. Generate a join token | ||
|
|
||
| (!docs/pages/includes/tctl-token.mdx serviceName="Discovery" tokenType="discovery" tokenFile="/tmp/token" !) | ||
|
|
||
| (!docs/pages/includes/database-access/alternative-methods-join.mdx!) | ||
|
|
||
| ## Step 2/4. Configure the Discovery service | ||
|
|
||
| Enabling AWS database discovery requires that the `discovery_service.aws` | ||
| section includes at least one entry and that `discovery_service.aws.types` | ||
| includes one of database types listed in the sample YAML below. | ||
|
|
||
| Create a `teleport.yaml` file similar to the following on the host that will | ||
| run the Discovery Service: | ||
|
|
||
| ```yaml | ||
| version: v3 | ||
| teleport: | ||
| join_params: | ||
| token_name: "/tmp/token" | ||
| method: token | ||
| proxy_server: "<Var name="teleport.example.com:443"/>" | ||
| auth_service: | ||
| enabled: off | ||
| proxy_service: | ||
| enabled: off | ||
| ssh_service: | ||
| enabled: off | ||
| discovery_service: | ||
| enabled: "yes" | ||
| discovery_group: "aws-prod" | ||
| aws: | ||
| # Database types. Valid options are: | ||
| # 'rds' - discovers AWS RDS and Aurora databases. | ||
| # 'rdsproxy' - discovers AWS RDS Proxy databases. | ||
| # 'redshift' - discovers AWS Redshift databases. | ||
| # 'redshift-serverless' - discovers AWS Redshift Serverless databases. | ||
| # 'elasticache' - discovers AWS ElastiCache Redis databases. | ||
| # 'memorydb' - discovers AWS MemoryDB Redis databases. | ||
| # 'opensearch' - discovers AWS OpenSearch Redis databases. | ||
| - types: ["rds"] | ||
| regions: ["us-east-1"] | ||
| tags: | ||
| "env": "prod" # Match database resource tags where tag:env=prod | ||
|
|
||
| - types: ["redshift", "redshift-serverless"] | ||
| regions: ["us-west-1"] | ||
| tags: | ||
| "env": "prod" | ||
| # Optional AWS role that the Discovery Service will assume to discover | ||
| # AWS-hosted databases. The IAM identity assigned to the host must be able | ||
| # to assume this role. | ||
| assume_role_arn: "arn:aws:iam::123456789012:role/example-role-name" | ||
| # Optional AWS external ID that the Database Service will use to assume | ||
| # a role in an external AWS account. | ||
| external_id: "example-external-id" | ||
| ``` | ||
| Adjust the keys under `discovery_service.aws` to match your AWS databases. | ||
|
|
||
| (!docs/pages/includes/discovery/discovery-group.mdx!) | ||
|
|
||
| ## Step 3/4. Bootstrap IAM permissions | ||
|
|
||
| Create an IAM role and attach it to the host that will run the Discovery | ||
| Service. | ||
|
|
||
| Teleport can bootstrap IAM permissions for the Discovery Service using the | ||
| `teleport discovery bootstrap` command. You can use this command in automatic | ||
| or manual mode: | ||
|
|
||
| - In automatic mode, Teleport attempts to create the appropriate IAM policies | ||
| and attach them to the specified IAM roles. This requires IAM permissions to | ||
| create and attach IAM policies. | ||
| - In manual mode, Teleport prints the required IAM policies. You can then create | ||
| and attach them manually using the AWS management console. | ||
|
|
||
| <Tabs> | ||
| <TabItem label="Automatic"> | ||
| Either temporarily give IAM admin permissions to the host of the Discovery | ||
| Service or copy the service YAML configuration file to your desktop where you | ||
| have the IAM admin permissions. | ||
|
|
||
| Use this command to bootstrap the permissions automatically with YAML | ||
| configuration file of the Discovery Service: | ||
|
|
||
| ```code | ||
| $ teleport discovery bootstrap \ | ||
| --attach-to-role arn:aws:iam::<Var name="aws-account-id"/>:role/<Var name="iam-role-name"/> \ | ||
| --policy-name TeleportDatabaseDiscovery \ | ||
| -c <Var name="/etc/teleport.yaml"/> | ||
| ``` | ||
| </TabItem> | ||
|
|
||
| <TabItem label="Manual"> | ||
| Use the following command to display the required IAM policies that you need | ||
| to create in your AWS console: | ||
|
|
||
| ```code | ||
| $ teleport discovery bootstrap --manual \ | ||
| --attach-to-role arn:aws:iam::<Var name="aws-account-id"/>:role/<Var name="iam-role-name"/> \ | ||
| --policy-name TeleportDatabaseDiscovery \ | ||
| -c <Var name="/etc/teleport.yaml"/> | ||
| ``` | ||
| </TabItem> | ||
| </Tabs> | ||
|
|
||
| <Details title="Bootstrapping with assume_role_arn in config"> | ||
| When `assume_role_arn` is configured for AWS matchers, `teleport discovery | ||
| bootstrap` command determines the permissions required for the bootstrap target | ||
| AWS IAM identity using the following logic: | ||
|
|
||
| - When the target does not match `assume_role_arn` in any AWS matcher in the | ||
| configuration file, the target is assumed to be the Teleport Discovery | ||
| Service's AWS IAM identity and permissions are bootstrapped for all the AWS | ||
| matchers without `assume_role_arn`. | ||
| - When an `--attach-to-role` target matches an `assume_role_arn` setting for | ||
| AWS matchers in the configuration file, permissions are bootstrapped only for | ||
| those AWS matchers. | ||
|
|
||
| You will need to run the bootstrap command once with the Teleport Discovery | ||
| Service's IAM identity as the policy attachment target, and once for each AWS | ||
| IAM role that is used for `assume_role_arn`. | ||
| </Details> | ||
|
|
||
| ## Step 4/4. Use the Discovery Service | ||
|
|
||
| ### Start the Discovery Service | ||
|
|
||
| (!docs/pages/includes/start-teleport.mdx service="the Discovery Service"!) | ||
|
|
||
| After the Discovery Service starts, database servers matching the tags and | ||
| regions specified in the AWS section are added to the Teleport cluster | ||
| automatically. | ||
|
|
||
| ### List registered databases | ||
|
|
||
| You can list them with the `tctl get db` command or check a specific database | ||
| with `tctl get db/<database-name>`. | ||
|
|
||
| The default name of the discovered database includes the AWS resource ID, | ||
| endpoint and matcher types, AWS region and account ID to ensure uniqueness, for | ||
| example `my-postgres-rds-aurora-us-east-1-123456789012`. | ||
|
|
||
| A discovered database with the default name also has a shorter display name | ||
| that consists only the AWS resource ID and the endpoint type, for example | ||
| `my-postgres`, `my-postgres-reader`. Either the full name or the display name | ||
| can be used for `tctl` and `tsh` commands. | ||
|
|
||
| You can override the default name by applying the `TeleportDatabaseName` AWS | ||
| tag to the AWS database resource. | ||
|
|
||
| ## Next | ||
| - Learn about [Dynamic Registration](../database-access/guides/dynamic-registration.mdx) by the | ||
| Teleport Database Service. | ||
| - Get started by [connecting](../database-access/guides.mdx) your database. | ||
| - Connect AWS databases in [external AWS accounts](../database-access/enroll-aws-databases/aws-cross-account.mdx). | ||
|
|
||
| ## Troubleshooting | ||
|
|
||
| (!docs/pages/includes/discovery/discovery-service-troubleshooting.mdx resourceKind="database" tctlResource="db" !) | ||
|
|
||
| (!docs/pages/includes/discovery/database-service-troubleshooting.mdx!) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
40 changes: 40 additions & 0 deletions
40
docs/pages/includes/discovery/database-service-troubleshooting.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,40 @@ | ||
| ### Database Service | ||
|
|
||
| If the `tctl get db` command returns the discovered databases you expect, but | ||
| the `tctl db ls` command does not include them, check that you have set the | ||
| `db_service.resources` section correctly, for example: | ||
|
|
||
| ```yaml | ||
| db_service: | ||
| enabled: "yes" | ||
| resources: | ||
| - labels: | ||
| "env": "prod" | ||
| ``` | ||
| If the section is correctly configured, but databases still do not appear, | ||
| check that you have the correct permissions to list databases in Teleport. | ||
| If there are connection errors when you try to connect to a database, then | ||
| first check if there are multiple `db_server` heartbeat resources for the target | ||
| database: `tctl get db_server/yourDatabaseName`. | ||
| If there are, it means that multiple Teleport Database Service instances are | ||
| proxying the database - this is an HA setup that will complicate | ||
| troubleshooting. | ||
| Teleport will choose one of those Database Service instances at random to proxy | ||
| the connection and if one of them can't reach the database endpoint or lacks | ||
| permissions, then you will see random connection errors. | ||
| {/* TODO(gavin): once we add healthchecks, we can remove this advice. HA shouldn't make connections randomly fail. */} | ||
|
|
||
| Even if connection errors are consistent, you should scale down or reconfigure | ||
| your Teleport Database Service instances such that only one matches the target `db` | ||
| while you are troubleshooting errors. | ||
| Verify that there is only one `db_server` with `tctl get db_server/yourDatabaseName` | ||
| and then try the connection again. | ||
|
|
||
| Check the Teleport Database Service logs with DEBUG level logging enabled and | ||
| look for network or permissions errors. | ||
|
|
||
| There may be more specifc troubleshooting steps for a particular type of | ||
| database in the | ||
| [database access guides](../../database-access/introduction.mdx#connect-your-database). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
18 changes: 18 additions & 0 deletions
18
docs/pages/includes/discovery/discovery-service-troubleshooting.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,18 @@ | ||
| ### Discovery Service | ||
|
|
||
| To check if the Discovery Service is working correctly, you can check if any | ||
| {{ resourceKind }}s have been discovered. | ||
| To do this, you can use the `tctl get {{ tctlResource }}` command and check if the | ||
| expected {{ resourceKind }}s have already been registered with your Teleport | ||
| cluster. | ||
|
|
||
| If some {{ resourceKind }}s do not appear in the list, check if the Discovery | ||
| Service selector labels match the missing {{ resourceKind }} tags or look into | ||
| the Discovery Service logs for permission errors. | ||
|
|
||
| If you are running multiple Discovery Services, you must ensure that each | ||
| service is configured with the same `discovery_group` value if they are watching | ||
| the same cloud {{ resourceKind }}s or a different value if they are watching different | ||
| cloud {{ resourceKind }}s. | ||
| If this is not configured correctly, a typical symptom is `{{ tctlResource }}` | ||
| resources being intermittently deleted from your Teleport cluster's registry. |
18 changes: 18 additions & 0 deletions
18
docs/pages/includes/discovery/kubernetes-service-troubleshooting.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,18 @@ | ||
| ### Kubernetes Service | ||
|
|
||
| If the `tctl get kube_cluster` command returns the discovered clusters, but the | ||
| `tctl kube ls` command does not include them, check that you have set the | ||
| `kubernetes_service.resources` section correctly. | ||
|
|
||
| ```yaml | ||
| kubernetes_service: | ||
| enabled: "yes" | ||
| resources: | ||
| - labels: | ||
| "env": "prod" | ||
| ``` | ||
| If the section is correctly configured, but clusters still do not appear or | ||
| return authentication errors, please check if permissions have been correctly configured | ||
| in your target cluster or that you have the correct permissions to list Kubernetes clusters | ||
| in Teleport. |
Oops, something went wrong.