Version: 18.x

Dynamic Database Registration

Is this page helpful?

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.

This page describes the Teleport configuration options that allow you to enable and customize dynamic database registration.

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: true
  resources:
  - labels:
      "*": "*"

You can use a wildcard selector to register all dynamic database 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

Check that you can connect to your Teleport cluster and verify that you can run tctl and tsh commands using your current credentials.
1. Assign teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and [email protected] to your Teleport username.
2. Authenticate to your Teleport cluster. This depends on whether your shell is interactive or not.
  
  In an interactive shell: Run the following command. By default, this triggers a multi-factor authentication prompt:
```
tsh login --proxy=teleport.example.com --user=[email protected]
tctl status
Cluster  teleport.example.com
Version  18.10.0
CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
```
  On non-interactive environments: If you are running tsh and tctl as an AI agent, in a CI/CD environment, or similar, make sure the TELEPORT_IDENTITY_FILE environment variable is assigned to a valid file path with credentials for your cluster. tsh and tctl read the file path from the environment variable and do not require a separate authentication step. If there is no identity file available, we recommend that you set up Machine ID to provision one automatically.
  
  When executing tctl commands with an identity file, you must pass the --auth-server flag to provide the Teleport Auth Service address, which is not included in the identity file. If you provide the Proxy Service address, tctl connects to the Proxy Service, which forwards traffic to and from the Teleport Auth Service. Update 443 to 3025 if you are contacting the Auth Service directly with tctl:
```
tctl status --auth-server=teleport.example.com:443
```
  For tsh commands that read an identity file, you must pass the --proxy flag, which points tsh to the address of the Teleport Proxy Service:
```
tsh status --proxy=teleport.example.com
```
  Ensure client commands can access your identity file. Replace path/to/identity/file with the path to your identity file:
```
export TELEPORT_IDENTITY_FILE="${TELEPORT_IDENTITY_FILE:-path/to/identity/file}"
```
  Add the --auth-server or --proxy flags to all subsequent tctl and tsh commands.
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.

Was this page helpful?