From 02d9ff3e478bb88ef29ba77da792525835900807 Mon Sep 17 00:00:00 2001 From: Gavin Frazar Date: Mon, 17 Jun 2024 16:04:49 -0700 Subject: [PATCH] add database discovery overview * 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 --- docs/config.json | 8 +- docs/pages/auto-discovery/databases.mdx | 365 ++++++++++-------- docs/pages/auto-discovery/databases/aws.mdx | 181 +++++++++ docs/pages/auto-discovery/kubernetes.mdx | 2 +- docs/pages/auto-discovery/kubernetes/aws.mdx | 6 +- .../pages/auto-discovery/kubernetes/azure.mdx | 6 +- .../kubernetes/google-cloud.mdx | 6 +- .../enroll-azure-databases.mdx | 2 +- .../database-service-troubleshooting.mdx | 40 ++ .../includes/discovery/discovery-config.yaml | 21 +- .../includes/discovery/discovery-group.mdx | 3 +- .../discovery-service-troubleshooting.mdx | 18 + .../kubernetes-service-troubleshooting.mdx | 18 + .../includes/discovery/step-description.mdx | 24 +- .../includes/discovery/troubleshooting.mdx | 27 -- 15 files changed, 508 insertions(+), 219 deletions(-) create mode 100644 docs/pages/auto-discovery/databases/aws.mdx create mode 100644 docs/pages/includes/discovery/database-service-troubleshooting.mdx create mode 100644 docs/pages/includes/discovery/discovery-service-troubleshooting.mdx create mode 100644 docs/pages/includes/discovery/kubernetes-service-troubleshooting.mdx delete mode 100644 docs/pages/includes/discovery/troubleshooting.mdx diff --git a/docs/config.json b/docs/config.json index 0ec9c32dd3b9e..27b3105db6ebb 100644 --- a/docs/config.json +++ b/docs/config.json @@ -968,7 +968,13 @@ }, { "title": "Databases", - "slug": "/auto-discovery/databases/" + "slug": "/auto-discovery/databases/", + "entries": [ + { + "title": "AWS", + "slug": "/auto-discovery/databases/aws/" + } + ] }, { "title": "Kubernetes Applications", diff --git a/docs/pages/auto-discovery/databases.mdx b/docs/pages/auto-discovery/databases.mdx index eec0c3ae7aa53..91fe8e616cbef 100644 --- a/docs/pages/auto-discovery/databases.mdx +++ b/docs/pages/auto-discovery/databases.mdx @@ -1,183 +1,226 @@ --- -title: AWS Database Auto-Discovery -description: How to configure Teleport to discover AWS-hosted databases. +title: Database Discovery +description: Detailed guides for configuring database discovery. --- -Database discovery involves two components. +Teleport can be configured to discover databases automatically and register +them with your Teleport cluster. -The first, the Discovery Service, is responsible for watching your cloud -provider and checking if there are any new databases or if there have been any -modifications to previously discovered databases. +## Supported clouds -The second, the Database Service, monitors the databases created by the -Discovery Service and proxies communications between users and the database -servers hosted by the cloud provider. +- [AWS](./databases/aws.mdx): Discovery for AWS databases. +- [Azure](../database-access/enroll-azure-databases.mdx): Discovery for Azure databases. +{/* TODO(gavin): Add an Azure discovery guide and permission reference */} -In this guide, you will configure a Teleport Discovery Service instance to -discover AWS-hosted databases automatically. +## Architecture overview -## Prerequisites +Database auto-discovery consists of the following components: -(!docs/pages/includes/edition-prereqs-tabs.mdx!) +1. One or more Teleport Discovery Service instances polling APIs to discover and + register databases with your Teleport cluster. +1. One or more Teleport Database Service instances forwarding database + connections to the discovered databases. -- 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. +Both the Discovery Service and Database Service can be configured in the same Teleport +process or separate processes. +We recommend running them as separate processes to decouple database discovery +from database access. -## Step 1/4. Generate a join token +## How the Discovery Service works -(!docs/pages/includes/tctl-token.mdx serviceName="Discovery" tokenType="discovery" tokenFile="/tmp/token" !) +The Teleport Discovery Service is responsible for polling APIs for databases +that match its configured selectors. +When the Discovery Service matches a database, it will +[dynamically register the database](../database-access/guides/dynamic-registration.mdx) +with your Teleport cluster. +The dynamic `db` resources it creates in your Teleport cluster will include +information such as: -(!docs/pages/includes/database-access/alternative-methods-join.mdx!) +- *Name*: Database name, with additional identifying information appended to it + to avoid colliding with other `db` names in your Teleport cluster +- *Labels* + - Imported database tags + - Database location/region + - Cloud account information, e.g. AWS Account ID / Azure Subscription ID +- *Endpoint Info*: Connection endpoint the database can be reached at -## Step 2/4. Configure the Discovery service + +You can override a discovered database's name by using a special tag attached +to the database in your cloud provider: + - ***key***: `TeleportDatabaseName` + - ***value***: desired name -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. +The Discovery Service will check if the database metadata includes the tag and +use its value as the resource name in Teleport. +The name override will be used verbatim, i.e. additional metadata will not be +appended to it. + -Create a `teleport.yaml` file similar to the following on the host that will -run the Discovery Service: +The Teleport Discovery Service only needs access to APIs that it can poll for +databases - it does not need network connectivity or permissions to connect to +any databases. + +In addition to registering new databases, the Discovery Service also removes +— from Teleport's registry — the databases that have been deleted or that no +longer match the Discovery Service's configured selectors. + +(!docs/pages/includes/discovery/discovery-group.mdx!) + +## Discovery Service configuration + +Here's an example database discovery configuration for the Discovery Service: ```yaml -version: v3 -teleport: - join_params: - token_name: "/tmp/token" - method: token - proxy_server: "" -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" + enabled: true + # discovery_group is used to group discovered resources into different + # sets. This is required when you have multiple Teleport Discovery services + # running. It prevents discovered services from colliding in Teleport when + # managing discovered resources. + # If two Discovery Services match the same resources, they must be in the + # same discovery group. + # If two Discovery Services match different resources, they must be in + # different discovery groups. + discovery_group: "disc-group" + # poll_interval is the cadence at which the discovery server will run each of its + # discovery cycles. The default is 5m. + poll_interval: 5m + # Matchers for discovering AWS-hosted resources. + aws: + # AWS resource types to discover and register with your Teleport cluster. + # Valid database discovery options are: + # 'rds' - Amazon RDS and Aurora databases. + # 'rdsproxy' - Amazon RDS Proxy databases. + # 'redshift' - Amazon Redshift databases. + # 'redshift-serverless' - Amazon Redshift Serverless databases. + # 'elasticache' - Amazon ElastiCache Redis databases. + # 'memorydb' - Amazon MemoryDB Redis databases. + # 'opensearch' - Amazon OpenSearch Redis databases. + - types: ["rds"] + # AWS regions to search for resources from + regions: ["us-east-1","us-west-1"] + # Optional AWS resource tags to match when registering resources + # Defaults to a wildcard selector that matches any resource: "*":"*" + tags: + "env": "prod" + # Optional AWS role that the Discovery Service will assume to discover + # and register AWS-hosted resources. + assume_role_arn: "arn:aws:iam::123456789012:role/rds-discovery" + # Optional AWS external ID that the Discovery 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. +The `discovery_service.aws[]` setting is a list of selectors for AWS resources. +This example configures the Teleport Discovery Service to poll AWS for Amazon +RDS databases in the us-east-1 and us-west-1 regions. +It will assume an AWS IAM role in the `123...` AWS account, which has +the permissions necessary for RDS database discovery. +Here's how it works in detail: + +1. **Provider type:** The Discovery Service can discover resources + hosted by different providers. Each provider type has its own configuration + section. + The Discovery Service will poll the provider API for resources based on a + configured list of selectors for that provider. + Each selector will be used by the Discovery Service when it polls the provider + API. + In this example, the provider configuration is for AWS. +1. **Permissions:** The Discovery Service will need access to credentials that + it can use to authenticate itself to the provider API. If + `discovery_service.aws[].assume_role_arn` is configured, then the Discovery + Service will first assume that AWS IAM role before making further API calls + for resource discovery. This means one Discovery Service can be used to + discover resources across multiple AWS accounts by assuming an external role. + It can also be useful to simplify IAM configuration - you can configure + a Discovery Service to use a different role depending on the type of resources + it needs to discover. + In this example, the Discovery Service will assume the "rds-discovery" IAM role + which, as the name implies, only has the permissions necessary for RDS + database discovery. +1. **Selectors:** + When a resource is found via a provider API, the Discovery Service will + check the corresponding selector tags/labels to determine whether it should + register that resource. + If the selector matches, then the Discovery Service will dynamically register + that resource with your Teleport cluster. For databases, that means it will + create a `db` resource. + In this example, the Discovery Service will poll for Amazon RDS databases in + the us-east-1 and us-west-1 regions and register `db` resources in your + Teleport cluster for any RDS databases that have the AWS tag "env: prod". + +For more information about Discovery Service configuration, refer to +[one of the guides above](#supported-clouds) or the +[Discovery Service Configuration Reference](../reference/config.mdx#discovery-service). + +## How the Database Service works + +The Teleport Database Service is responsible for monitoring +[dynamically registered](../database-access/guides/dynamic-registration.mdx) +`db` resources in your Teleport cluster and acting as a connection proxy for the +databases they represent. + +The Database Service must be configured with label selectors to match `db` +resources. +When a `db` resource is matched, the Database Service creates a `db_server` +heartbeat to signal to your Teleport cluster that it can provide access to the +database that the `db` resource represents. +The Database Service must have network connectivity to the database endpoint and +permissions to authenticate to the database. +The permissions it needs vary by database type, so refer to Teleport's +[database access guides](../database-access/introduction.mdx#connect-your-database) +for detailed permissions information. + +## Database Service configuration + +Here's an example configuration for the Database Service: -(!docs/pages/includes/discovery/discovery-group.mdx!) +```yaml +db_service: + enabled: true + # Matchers for dynamic db resources created with the "tctl create" command or by database auto-discovery. + resources: + - labels: + # These labels, among others, are added automatically by the Discovery + # Service. + # "cloud" origin indicates that a `db` resource was created for a + # resource discovered in the cloud. + "teleport.dev/origin": "cloud" + # Cloud resources are also labeled to indicate which cloud provider + # they came from. + "teleport.dev/cloud": "AWS" + # Specific to AWS. This is the AWS account ID. + "account-id": "123456789012" + aws: + # This is an optional AWS role ARN to assume when forwarding connections + # to AWS databases. + # The Database Service's IAM identity must be allowed to assume this + # role. + assume_role_arn: "arn:aws:iam::123456789012:role/StagingDBAccess" + - labels: + "teleport.dev/origin": "cloud" + "teleport.dev/cloud": "AWS" + "account-id": "222222222222" + aws: + assume_role_arn: "arn:aws:iam::222222222222:role/ProdDBAccess" + # External ID is an optional value that should be set when accessing + # your AWS account from a third-party service (delegated access). + external_id: "exampleID123" +``` -## 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. - - - - 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:::role/ \ - --policy-name TeleportDatabaseDiscovery \ - -c - ``` - - - - 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:::role/ \ - --policy-name TeleportDatabaseDiscovery \ - -c - ``` - - - -
-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`. -
- -## 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/`. - -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). +The `db_service.resources[]` setting is a list of label selectors. +This example configures the Teleport Database Service to match AWS databases +discovered in two accounts: `123...` and `222...`. +For each account it will assume a different AWS IAM role. +Here's how it works in detail: + +1. **Label matching:** The Database Service monitors `db` resources and the + first label selector in `db_service.resources[].labels` that matches a `db` + will be used. If no selector matches, then the `db` resource is ignored. +1. **Permissions:** The Database Service will assume the identity configured in + the label selector that matched. If the selector does not specify an identity, + then the Database Service will use its own identity. +1. **Connection:** The Database Service, acting as either its own identity or + the identity it assumed, will retrieve credentials to authenticate to the + database and use those credentials to act as a proxy for an authorized + Teleport user. diff --git a/docs/pages/auto-discovery/databases/aws.mdx b/docs/pages/auto-discovery/databases/aws.mdx new file mode 100644 index 0000000000000..ce651a6978557 --- /dev/null +++ b/docs/pages/auto-discovery/databases/aws.mdx @@ -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: "" +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. + + + + 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:::role/ \ + --policy-name TeleportDatabaseDiscovery \ + -c + ``` + + + + 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:::role/ \ + --policy-name TeleportDatabaseDiscovery \ + -c + ``` + + + +
+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`. +
+ +## 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/`. + +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!) diff --git a/docs/pages/auto-discovery/kubernetes.mdx b/docs/pages/auto-discovery/kubernetes.mdx index 1198c54617cd3..e6a7d845b26b7 100644 --- a/docs/pages/auto-discovery/kubernetes.mdx +++ b/docs/pages/auto-discovery/kubernetes.mdx @@ -180,4 +180,4 @@ matching mechanism to identify and manage the EKS clusters. cluster. Both services — Discovery and Kubernetes — can be configured in the same -Teleport process or separate processes. \ No newline at end of file +Teleport process or separate processes. diff --git a/docs/pages/auto-discovery/kubernetes/aws.mdx b/docs/pages/auto-discovery/kubernetes/aws.mdx index 14cb1b0c6550b..b3b962e6161ee 100644 --- a/docs/pages/auto-discovery/kubernetes/aws.mdx +++ b/docs/pages/auto-discovery/kubernetes/aws.mdx @@ -7,7 +7,7 @@ EKS Auto-Discovery can automatically discover any EKS cluster and enroll it in Teleport if its tags match the configured labels. -(!docs/pages/includes/discovery/step-description.mdx!) +(!docs/pages/includes/discovery/step-description.mdx serviceName="Kubernetes" resourceDesc="cluster" resourceKind="kube_cluster" !) ## How it works @@ -366,4 +366,6 @@ automatically. ## Troubleshooting -(!docs/pages/includes/discovery/troubleshooting.mdx!) +(!docs/pages/includes/discovery/discovery-service-troubleshooting.mdx resourceKind="Kubernetes cluster" tctlResource="kube_cluster" !) + +(!docs/pages/includes/discovery/kubernetes-service-troubleshooting.mdx!) diff --git a/docs/pages/auto-discovery/kubernetes/azure.mdx b/docs/pages/auto-discovery/kubernetes/azure.mdx index 3a1a25802997e..3f39c268754e8 100644 --- a/docs/pages/auto-discovery/kubernetes/azure.mdx +++ b/docs/pages/auto-discovery/kubernetes/azure.mdx @@ -7,7 +7,7 @@ AKS Auto-Discovery can automatically discover any AKS cluster and enroll it in Teleport if its tags match the configured labels. -(!docs/pages/includes/discovery/step-description.mdx!) +(!docs/pages/includes/discovery/step-description.mdx serviceName="Kubernetes" resourceDesc="cluster" resourceKind="kube_cluster" !) ## Prerequisites @@ -261,4 +261,6 @@ specified in the Azure section will be added to the Teleport cluster automatical ## Troubleshooting -(!docs/pages/includes/discovery/troubleshooting.mdx!) \ No newline at end of file +(!docs/pages/includes/discovery/discovery-service-troubleshooting.mdx resourceKind="Kubernetes cluster" tctlResource="kube_cluster" !) + +(!docs/pages/includes/discovery/kubernetes-service-troubleshooting.mdx!) diff --git a/docs/pages/auto-discovery/kubernetes/google-cloud.mdx b/docs/pages/auto-discovery/kubernetes/google-cloud.mdx index 2d11ad05fe350..7fa1ff7352e29 100644 --- a/docs/pages/auto-discovery/kubernetes/google-cloud.mdx +++ b/docs/pages/auto-discovery/kubernetes/google-cloud.mdx @@ -14,7 +14,7 @@ Discovery for GKE. ## Overview -(!docs/pages/includes/discovery/step-description.mdx!) +(!docs/pages/includes/discovery/step-description.mdx serviceName="Kubernetes" resourceDesc="cluster" resourceKind="kube_cluster" !) ## Prerequisites @@ -638,4 +638,6 @@ will update its state to reflect the available clusters in your account. ## Troubleshooting -(!docs/pages/includes/discovery/troubleshooting.mdx!) +(!docs/pages/includes/discovery/discovery-service-troubleshooting.mdx resourceKind="Kubernetes cluster" tctlResource="kube_cluster" !) + +(!docs/pages/includes/discovery/kubernetes-service-troubleshooting.mdx!) diff --git a/docs/pages/database-access/enroll-azure-databases.mdx b/docs/pages/database-access/enroll-azure-databases.mdx index 52f08daf864fd..e09f2c074e16a 100644 --- a/docs/pages/database-access/enroll-azure-databases.mdx +++ b/docs/pages/database-access/enroll-azure-databases.mdx @@ -6,6 +6,6 @@ description: "Provides instructions on protecting databases in your Azure-manage You can protect Azure-managed databases with Teleport. Learn how to enroll the following databases: -- [Azure SQl Server](./enroll-azure-databases/azure-sql-server-ad.mdx) +- [Azure SQL Server](./enroll-azure-databases/azure-sql-server-ad.mdx) - [Azure Database for PostgreSQL or MySQL Server](./enroll-azure-databases/azure-postgres-mysql.mdx) - [Azure Redis](./enroll-azure-databases/azure-redis.mdx) diff --git a/docs/pages/includes/discovery/database-service-troubleshooting.mdx b/docs/pages/includes/discovery/database-service-troubleshooting.mdx new file mode 100644 index 0000000000000..1d21c53f833cb --- /dev/null +++ b/docs/pages/includes/discovery/database-service-troubleshooting.mdx @@ -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). diff --git a/docs/pages/includes/discovery/discovery-config.yaml b/docs/pages/includes/discovery/discovery-config.yaml index dea797df655e7..3e5de35e69635 100644 --- a/docs/pages/includes/discovery/discovery-config.yaml +++ b/docs/pages/includes/discovery/discovery-config.yaml @@ -13,16 +13,17 @@ discovery_service: # discovery cycles. The default is 5m. poll_interval: 5m aws: - # AWS resource types. Valid options are: - # 'ec2' - discovers and registers AWS EC2 instances. - # 'eks' - discovers and registers AWS EKS clusters. - # 'rds' - discovers and registers AWS RDS and Aurora databases. - # 'rdsproxy' - discovers and registers AWS RDS Proxy databases. - # 'redshift' - discovers and registers AWS Redshift databases. - # 'redshift-serverless' - discovers and registers AWS Redshift Serverless databases. - # 'elasticache' - discovers and registers AWS ElastiCache Redis databases. - # 'memorydb' - discovers and registers AWS MemoryDB Redis databases. - # 'opensearch' - discovers and registers AWS OpenSearch Redis databases. + # AWS resource types to discover and register with your Teleport cluster. + # Valid options are: + # 'ec2' - Amazon EC2 instances. + # 'eks' - Amazon EKS clusters. + # 'rds' - Amazon RDS and Aurora databases. + # 'rdsproxy' - Amazon RDS Proxy databases. + # 'redshift' - Amazon Redshift databases. + # 'redshift-serverless' - Amazon Redshift Serverless databases. + # 'elasticache' - Amazon ElastiCache Redis databases. + # 'memorydb' - Amazon MemoryDB Redis databases. + # 'opensearch' - Amazon OpenSearch Redis databases. - types: ["ec2"] # AWS regions to search for resources from regions: ["us-east-1","us-west-1"] diff --git a/docs/pages/includes/discovery/discovery-group.mdx b/docs/pages/includes/discovery/discovery-group.mdx index da3b6a9954a38..ce3b48854da9b 100644 --- a/docs/pages/includes/discovery/discovery-group.mdx +++ b/docs/pages/includes/discovery/discovery-group.mdx @@ -18,5 +18,4 @@ the following configuration. from Production account. - 2 Discovery Services configured with `discovery_group: "staging"` polling data from Staging account. - - \ No newline at end of file + diff --git a/docs/pages/includes/discovery/discovery-service-troubleshooting.mdx b/docs/pages/includes/discovery/discovery-service-troubleshooting.mdx new file mode 100644 index 0000000000000..19c92b7dca9f6 --- /dev/null +++ b/docs/pages/includes/discovery/discovery-service-troubleshooting.mdx @@ -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. diff --git a/docs/pages/includes/discovery/kubernetes-service-troubleshooting.mdx b/docs/pages/includes/discovery/kubernetes-service-troubleshooting.mdx new file mode 100644 index 0000000000000..d95e7491bceea --- /dev/null +++ b/docs/pages/includes/discovery/kubernetes-service-troubleshooting.mdx @@ -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. diff --git a/docs/pages/includes/discovery/step-description.mdx b/docs/pages/includes/discovery/step-description.mdx index 6b5e370e7d7b8..1ba3fb3068a38 100644 --- a/docs/pages/includes/discovery/step-description.mdx +++ b/docs/pages/includes/discovery/step-description.mdx @@ -1,18 +1,22 @@ -Teleport Kubernetes Auto-Discovery involves two components. +Teleport {{ serviceName }} auto-discovery involves two components. The first, the Discovery Service, is responsible for watching your cloud -provider and checking if there are any new clusters or if there have been any -modifications to previously discovered clusters. The second, the Kubernetes -Service, monitors the clusters created by the Discovery Service. It proxies -communications between users and the API servers of these clusters. +provider and checking if there are any new {{ resourceDesc }}s or if there have +been any modifications to previously discovered {{ resourceDesc }}s. It +dynamically registers each discovered {{ resourceDesc }} as a +`{{ resourceKind }}` resource in your Teleport cluster. +The second, the {{ serviceName }} Service, monitors the dynamic +`{{ resourceKind }}` resources registered by the Discovery Service. +It proxies communications between users and the {{ resourceDesc }}. -This guide presents the Discovery Service and Kubernetes Service running in the -same process, however both can run independently and on different machines. +This guide presents the Discovery Service and {{ serviceName }} Service running +in the same process, however both can run independently and on different machines. -For example, you can run an instance of the Kubernetes Service in each -Kubernetes cluster you want to register with Teleport, and an instance of the -Discovery Service in any network you wish. +For example, you can run an instance of the {{ serviceName }} Service in the +same private network as the {{ resourceDesc }}s you want to register with your +Teleport cluster, and an instance of the Discovery Service in any network you +wish. diff --git a/docs/pages/includes/discovery/troubleshooting.mdx b/docs/pages/includes/discovery/troubleshooting.mdx deleted file mode 100644 index a89d3e7145d83..0000000000000 --- a/docs/pages/includes/discovery/troubleshooting.mdx +++ /dev/null @@ -1,27 +0,0 @@ -### Discovery Service - -To check if the Discovery Service is working correctly, you can check if any Kubernetes -clusters have been discovered. To do this, you can use the `tctl get kube_cluster` -command and inspect if the expected clusters have already been imported into Teleport. - -If some clusters do not appear in the list, check if the filtering labels match -the missing cluster tags or look into the service logs for permission errors. - -### Kubernetes Service - -If the `tctl get kube_cluster` command returns the discovered clusters, but the -`tsh kube ls` command does not include them, check that you have set the -`kubernetes_service.resources` section correctly. - -```yaml -kubernetes_service: - enabled: "yes" - resources: - - tags: - "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.