AWS Database Auto-Discovery

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 version 15.2.4 or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

• The tctl admin tool and tsh client tool.

  On Teleport Enterprise, you must use the Enterprise version of tctl, which you can download from your Teleport account workspace. Otherwise, visit Installation for instructions on downloading tctl and tsh for Teleport Community Edition.

• 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

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.

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.

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

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

Step 4/4. Use the Discovery Service

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.

sudo systemctl enable teleport
sudo systemctl 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.

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 by the Teleport Database Service.
• Get started by connecting your database.
• Connect AWS databases in external AWS accounts.