![Fork me on GitHub](/docs/_next/image/?url=%2Fdocs%2F_next%2Fstatic%2Fmedia%2Fforkme.b9234619.webp&w=256&q=75)
Teleport
Database Discovery
- Version 17.x
- Version 16.x
- Version 15.x
- Version 14.x
- Older Versions
Teleport can be configured to discover databases automatically and register them with your Teleport cluster.
Supported clouds
Architecture overview
Database auto-discovery consists of the following components:
- One or more Teleport Discovery Service instances polling APIs to discover and register databases with your Teleport cluster.
- 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
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
- Endpoint Info: Connection endpoint the database can be reached at
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.
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.
Discovery Service exposes a configuration parameter - discovery_service.discovery_group
-
that allows you to group discovered resources into different sets. This parameter
is used to prevent Discovery Agents watching different sets of cloud resources
from colliding against each other and deleting resources created by another services.
When 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 resources
or a different value if they are watching different cloud resources.
It is possible to run a mix of configurations in the same Teleport cluster meaning that some Discovery Services can be configured to watch the same cloud resources while others watch different resources. As an example, a 4-agent high availability configuration analyzing data from two different cloud accounts would run with the following configuration.
- 2 Discovery Services configured with
discovery_group: "prod"
polling data from Production account. - 2 Discovery Services configured with
discovery_group: "staging"
polling data from Staging account.
Discovery Service configuration
Here's an example database discovery configuration for the Discovery Service:
discovery_service:
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.
# '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:
- 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.
- 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. - 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 registerdb
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 or the Discovery Service Config File Reference.
How the Database Service works
The Teleport Database Service is responsible for monitoring
dynamically registered
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
for detailed permissions information.
Database Service configuration
Here's an example configuration for the Database Service:
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:
- Label matching: The Database Service monitors
db
resources and the first label selector indb_service.resources[].labels
that matches adb
will be used. If no selector matches, then thedb
resource is ignored. - 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.
- 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.