mirror of
https://github.com/gravitational/teleport.git
synced 2026-10-12 02:15:01 +00:00
Paul Gottschling
0d1113f5de
* Consolidate Reference docs section contents Closes #56206 Reduce the number of first-level children in the Reference section of the docs from 23 to 9, not counting the index page available at `/docs/reference/`. This makes the Reference section easier to navigate, since a user can more readily form a mental model of the content available in the section with fewer items and a more thematic organization. - Add a section for deployment references, consolidating reference guides for configuring and architecting a Teleport deployment. - Move the Predicate Language and User Types references into the Access Controls section of References. - Add a section for API reference guides, consolidating the Terraform, MWI Terraform, and Operator sections. - Move Cloud FAQ to Quick Links. This places the guide next to the main FAQ in the sidebar to make it more discoverable, since the guide is currently rather hidden. This also helps pave the way to merge the two FAQs in the future. * Add an MWI reference section The MWI Terraform module reference does not belong with reference guides for API clients. Add a section to the reference guide for Machine & Workload Identity. * Rename "API" to "Infrastructure as Code" Teleport users expect tctl, Operator, and Terraform Provider docs to be in an Infrastructure as Code reference section, rather than the more vague "API" section. Responds to **ravicious** feedback.
227 lines
10 KiB
Plaintext
227 lines
10 KiB
Plaintext
---
|
|
title: Database Discovery
|
|
description: Detailed guides for configuring database discovery.
|
|
tags:
|
|
- conceptual
|
|
- zero-trust
|
|
- infrastructure-identity
|
|
---
|
|
|
|
Teleport can be configured to discover databases automatically and register
|
|
them with your Teleport cluster.
|
|
|
|
## Supported clouds
|
|
|
|
- [AWS](aws.mdx): Discovery for AWS databases.
|
|
- [Azure](../../database-access/enroll-azure-databases/enroll-azure-databases.mdx): Discovery for Azure databases.
|
|
{/* TODO(gavin): Add an Azure discovery guide and permission reference */}
|
|
|
|
## Architecture overview
|
|
|
|
Database auto-discovery consists of the following components:
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
## How the Discovery Service works
|
|
|
|
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:
|
|
|
|
- *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
|
|
- The type of database discovered corresponding to the matcher type, e.g.
|
|
"rds", "redshift", etc.
|
|
- *Endpoint Info*: Connection endpoint the database can be reached at
|
|
|
|
<Admonition type="tip">
|
|
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
|
|
|
|
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.
|
|
</Admonition>
|
|
|
|
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
|
|
discovery_service:
|
|
enabled: true
|
|
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 and Valkey databases.
|
|
# 'elasticache-serverless' - Amazon ElastiCache Serverless Redis or Valkey databases.
|
|
# 'memorydb' - Amazon MemoryDB Redis databases.
|
|
# 'opensearch' - Amazon OpenSearch Redis databases.
|
|
# 'docdb' - Amazon DocumentDB 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"
|
|
```
|
|
|
|
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 Config File Reference](../../../reference/deployment/config.mdx).
|
|
|
|
## 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/database-access.mdx)
|
|
for detailed permissions information.
|
|
|
|
## Database Service configuration
|
|
|
|
Here's an example configuration for the Database Service:
|
|
|
|
```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"
|
|
```
|
|
|
|
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.
|