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 restarting the database agents.

To enable dynamic registration, include a resources section in your database agent configuration with a list of resource label selectors you'd like this agent to monitor:

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

You can use a wildcard selector to monitor all database resources in the cluster, or provide a specific set of labels to monitor a subset:

resources:
- labels:
    "env": "prod"
    "engine": "postgres"
- labels:
    "env": "test"
    "engine": "mysql"

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 database services 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

tsh login --proxy=teleport.example.com [email protected]
tctl status
Cluster  teleport.example.com
Version  12.1.1
CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

tsh login --proxy=myinstance.teleport.sh [email protected]
tctl status
Cluster  myinstance.teleport.sh
Version  12.1.1
CA pin   sha256:sha-hash-here

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 agent, it will unregister and stop proxying it.

To delete a database resource, run:

tctl rm db/example