Skip to main content
Version: 14.x

Dynamic Database Registration

Dynamic database registration allows Teleport administrators to register new databases (or update/unregister existing ones) without having to update the static configuration and restart Teleport Database Service instances.

Dynamic registration also enables administrators to deploy multiple Database Service instances for high availability by configuring Database Service replicas to watch for the same database resources.

To enable dynamic registration, include a resources section in your Teleport Database Service configuration with a list of resource label selectors you'd like this service to monitor for registering:

db_service:
  enabled: "yes"
  resources:
  - labels:
      "*": "*"

You can use a wildcard selector to register all dynamic app resources in the cluster on the Database Service or provide a specific set of labels for a subset:

resources:
- labels:
    "env": "prod"
    "engine": "postgres"
- labels:
    "env": "test"
    "engine": "mysql"
  aws:
    # Optional AWS role that the Database Service will assume to access
    # this database.
    assume_role_arn: ""
    # Optional AWS external ID that the Database Service will use to assume
    # a role in an external AWS account.
    external_id: ""

By default, the Database Service authenticates with the database servers using the IAM identity assigned to the host running it or the assume_role_arn field defined in the dynamic resources.

You can use aws.assume_role_arn to overwrite the IAM identity. If the role requires an external ID, use aws.external_id. The IAM identity assigned to the host must be able to assume the specified role.

Next define a database resource:

kind: db
version: v3
metadata:
  name: example
  description: "Example database"
  labels:
    env: prod
    engine: postgres
spec:
  protocol: "postgres"
  uri: "localhost:5432"

The user creating the dynamic registration needs to have a role with access to the database labels and the db resource. In this example role the user can only create and maintain databases labeled env: prod and engine: postgres.

kind: role
metadata:
  name: dynamicregexample
spec:
  allow:
    db_labels:
      engine: postgres
      env: prod
    rules:
    - resources:
      - db
      verbs:
      - list
      - create
      - read
      - update
      - delete
version: v5

See the full database resource spec reference.

To create a database resource, run:

$ tctl create database.yaml
  • To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. tctl is supported on macOS and Linux machines. For example: 
    $ tsh login --proxy=teleport.example.com [email protected]
    $ tctl status
    # Cluster  teleport.example.com
    # Version  14.3.33
    # CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
    If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

After the resource has been created, it will appear among the list of available databases (in tsh db ls or UI) as long as at least one Database Service instance picks it up according to its label selectors.

To update an existing database resource, run:

$ tctl create -f database.yaml

If the updated resource's labels no longer match a particular database, it will unregister and stop proxying it.

To delete a database resource, run:

$ tctl rm db/example

Aside from tctl, dynamic resources can also be added by:

See Using Dynamic Resources to learn more about managing Teleport's dynamic resources in general.