{"token_count": 1382}

# 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.

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](https://goteleport.com/docs/installation/agents/high-availability.md) 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 [reference](https://goteleport.com/docs/reference/infrastructure-as-code/teleport-resources/database-v3.md).

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, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email\@example.com to your Teleport username:

  ```
  $ tsh login --proxy=teleport.example.com --user=email@example.com
  $ tctl status
  Cluster  teleport.example.com
  Version  19.0.0-dev
  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.

  Running `tctl` on a Teleport beam

  In some environments, for example on a Teleport beam, Teleport authentication must take place through a local identity file. On a Teleport beam, the identity file is available automatically, and `tctl` reads the file path from the `TELEPORT_IDENTITY_FILE` environment variable.

  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.

  On a beam, you must use the Proxy Service address, as the Auth Service is not exposed to the public internet. You can do so by using the `TELEPORT_PROXY` environment variable:

  ```
  $ tctl status --auth-server=${TELEPORT_PROXY}
  ```

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](https://goteleport.com/docs/enroll-resources/auto-discovery/databases.md)
- [Terraform Provider](https://goteleport.com/docs/configuration/terraform-provider.md)
- [Kubernetes Operator](https://goteleport.com/docs/configuration/teleport-operator.md)
- [Teleport API](https://goteleport.com/docs/zero-trust-access/api.md)

See [Using Dynamic Resources](https://goteleport.com/docs/configuration.md) to learn more about managing Teleport's dynamic resources in general.