Get StartedContact Sales
Fork me on GitHub

Teleport

AWS Database Auto-Discovery

Version 14.x
  • Available for:
  • OpenSource
  • Team
  • Cloud
  • Enterprise

Database discovery involves two components.

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.

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.

In this guide, you will configure a Teleport Discovery Service instance to discover AWS-hosted databases automatically.

Prerequisites

  • A running Teleport cluster. For details on how to set this up, see the Getting Started guide.

  • The tctl admin tool and tsh client tool version >= 14.2.0.

    See Installation for details.

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport v14.2.0 git:api/14.0.0-gd1e081e go1.21
  
tsh version
Teleport v14.2.0 go1.21
Proxy version: 14.2.0Proxy: teleport.example.com

  • A Teleport Team account. If you don't have an account, sign up to begin your free trial.

  • The Enterprise tctl admin tool and tsh client tool, version >= 14.1.3.

    You can download these tools from the Cloud Downloads page.

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport Enterprise v14.1.3 git:api/14.0.0-gd1e081e go1.21
  
tsh version
Teleport v14.1.3 go1.21
Proxy version: 14.1.3Proxy: teleport.example.com

  • A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.

  • The Enterprise tctl admin tool and tsh client tool version >= 14.2.0.

    You can download these tools by visiting your Teleport account workspace.

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport Enterprise v14.2.0 git:api/14.0.0-gd1e081e go1.21
  
tsh version
Teleport v14.2.0 go1.21
Proxy version: 14.2.0Proxy: teleport.example.com

  • A Teleport Enterprise Cloud account. If you don't have an account, sign up to begin a free trial of Teleport Team and upgrade to Teleport Enterprise Cloud.

  • The Enterprise tctl admin tool and tsh client tool version >= 14.1.3.

    You can download these tools from the Cloud Downloads page.

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport Enterprise v14.1.3 git:api/14.0.0-gd1e081e go1.21
  
tsh version
Teleport v14.1.3 go1.21
Proxy version: 14.1.3Proxy: teleport.example.com
  • 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

The Discovery Service requires a valid join token to connect to the cluster.

Generate a join token by running the following command against your Teleport Auth Service and save it in /tmp/token on the host that will run the Discovery Service.

tctl tokens add --type=discovery

For users with a lot of infrastructure in AWS, or who might create or recreate many instances, consider alternative methods for joining new EC2 instances running Teleport:

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:

version: v3
teleport:
  join_params:
    token_name: "/tmp/token"
    method: token
  proxy_server: "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.

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.

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:

teleport discovery bootstrap \  --attach-to-role arn:aws:iam::aws-account-id:role/iam-role-name \  --policy-name TeleportDatabaseDiscovery \  -c /etc/teleport.yaml

Use the following command to display the required IAM policies that you need to create in your AWS console:

teleport discovery bootstrap --manual \  --attach-to-role arn:aws:iam::aws-account-id:role/iam-role-name \  --policy-name TeleportDatabaseDiscovery \  -c /etc/teleport.yaml

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. Start the Discovery Service

Configure the Discovery Service to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed the Discovery Service.

On the host where you will run the Discovery Service, enable and start Teleport:

sudo systemctl enable teleport
sudo systemctl start teleport

On the host where you will run the Discovery Service, create a systemd service configuration for Teleport, enable the Teleport service, and start Teleport:

sudo teleport install systemd -o /etc/systemd/system/teleport.service
sudo systemctl enable teleport
sudo systemctl start teleport

You can check the status of the Discovery Service with systemctl status teleport and view its logs with journalctl -fu teleport.

After the Discovery Service starts, database servers matching the tags and regions specified in the AWS section are added to the Teleport cluster automatically.

You can list them with the tctl get db command or check a specific database with tctl get db/<database-name>.

Next