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"

To see the currently running Database Services, run tctl get db_services:

kind: db_service
metadata:
  expires: "2024-08-27T11:38:10.207175Z"
  name: 2b5207e3-a258-423e-a41d-e50ea2f0dfdc
spec:
  hostname: my-host
  resources:
  - labels:
      env: prod
      engine: postgres
  - labels:
      env: test
      engine: mysql
version: v1

The name within a db_service matches to the host ID of the agent running the Teleport Database Service.

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. For example:

  tsh login --proxy=teleport.example.com --user=email@example.com
  tctl status
  Cluster  teleport.example.com
  Version  17.0.2
  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:

• Auto-Discovery
• Terraform Provider
• Kubernetes Operator
• Teleport API

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