Database Access Configuration Reference

Database service configuration

The following snippet shows full YAML configuration of a Database Service appearing in teleport.yaml configuration file:

db_service:
  # Enables the Database Service.
  enabled: "yes"

  # Matchers for database resources created with "tctl create" command or by the
  # discovery service.
  resources:
    # See "Database labels reference" (https://goteleport.com/docs/database-access/reference/labels/)
    # to learn more on database labels.
  - labels:
      "*": "*"
    # Optional AWS role that the Database Service will assume to access the
    # databases.
    aws:
      assume_role_arn: "arn:aws:iam::123456789012:role/example-role-name"
      external_id: "example-external-id"

  # Matchers for registering AWS-hosted databases.
  aws:
    # Database types. Valid options are:
    # 'rds' - discovers and registers AWS RDS and Aurora databases.
    # 'rdsproxy' - discovers and registers AWS RDS Proxy databases.
    # 'redshift' - discovers and registers AWS Redshift databases.
    # 'redshift-serverless' - discovers and registers AWS Redshift Serverless databases.
    # 'elasticache' - discovers and registers AWS ElastiCache Redis databases.
    # 'memorydb' - discovers and registers AWS MemoryDB Redis databases.
    # 'opensearch' - discovers and registers AWS OpenSearch Redis databases.
  - types: ["rds", "rdsproxy","redshift", "redshift-serverless", "elasticache", "memorydb", "opensearch"]
    # AWS regions to register databases from.
    regions: ["us-west-1", "us-east-2"]
    # Optional AWS role that the Database Service will assume to discover
    # and register AWS-hosted databases.
    # Discovered databases are also accessed by the Database Service via
    # this role.
    assume_role_arn: "arn:aws:iam::123456789012:role/example-role-name"
    # Optional AWS external ID that the Database Service will use to assume
    # a role in an external AWS account.
    external_id: "example-external-id"
    # AWS resource tags to match when registering databases.
    tags:
      "*": "*"

  # Matchers for registering Azure-hosted databases.
  azure:
    # Database types. Valid options are:
    # 'mysql' - discovers and registers Azure MySQL databases.
    # 'postgres' - discovers and registers Azure PostgreSQL databases.
    # 'redis' - discovers and registers Azure Cache for Redis databases.
    # 'sqlserver' - discovers and registers Azure SQL Server databases.
  - types: ["mysql", "postgres", "redis", "sqlserver"]
    # Azure regions to register databases from. Valid options are:
    # '*' - discovers databases in all regions (default).
    # Any valid Azure region name. List all valid regions using the Azure "az" cli: `az account list-locations -o table`
    regions: ["eastus", "westus"]
    # Azure subscription IDs to register databases from. Valid options are:
    # '*' - discovers databases in all subscriptions (default).
    subscriptions: ["11111111-2222-3333-4444-555555555555"]
    # Azure resource groups to register databases from. Valid options are:
    # '*' - discovers databases in all resource groups within configured subscription(s) (default).
    resource_groups: ["group1", "group2"]
    # Azure resource tags to match when registering databases.
    tags:
      "*": "*"

  # Lists statically registered databases proxied by this agent.
  databases:
    # Name of the database proxy instance, used to reference in CLI.
  - name: "prod"

    # Free-form description of the database proxy instance.
    description: "Production database"

    # Database protocol. Valid options are:
    # "cassandra"
    # "clickhouse"
    # "clickhouse-http"
    # "cockroachdb"
    # "dynamodb"
    # "elasticsearch"
    # "mongodb"
    # "mysql"
    # "oracle"
    # "postgres"
    # "redis"
    # "snowflake"
    # "spanner"
    # "sqlserver"
    protocol: "postgres"

    # Database connection endpoint. Must be reachable from Database Service.
    uri: "postgres.example.com:5432"

    # Optional TLS configuration.
    tls:
      # TLS verification mode. Valid options are:
      # 'verify-full' - performs full certificate validation (default).
      # 'verify-ca' - the same as `verify-full`, but skips the server name validation.
      # 'insecure' - accepts any certificate provided by database (not recommended).
      mode: verify-full
      # Optional database DNS server name. It allows to override the DNS name on
      # a client certificate when connecting to a database.
      # Use only with 'verify-full' mode.
      server_name: db.example.com
      # Optional path to the CA used to validate the database certificate.
      ca_cert_file: /path/to/pem
      # Optional configuration that allows Teleport to trust certificate
      # authorities available on the host system. If not set (by default),
      # Teleport only trusts self-signed databases with TLS certificates signed
      # by Teleport's Database Server CA or the ca_cert_file specified in this
      # TLS setting. For cloud-hosted databases, Teleport downloads the
      # corresponding required CAs for validation.
      trust_system_cert_pool: false

    # MySQL only options.
    mysql:
      # The default MySQL server version reported by Teleport Proxy.
      # When this option is set the Database Agent doesn't try to check the MySQL server version.
      server_version: 8.0.28

    # Optional admin user configuration for Automatic User Provisioning.
    admin_user:
      # Name of the admin user.
      name: "teleport-admin"
      #  Optional default database the admin user logs into. See individual
      #  guides for default value.
      default_database: "teleport"

    # Optional AWS configuration for AWS hosted databases. AWS region- and
    # service-specific configurations can usually be auto-detected from the
    # endpoint.
    aws:
      # Region the database is deployed in.
      region: "us-east-1"
      # Optional AWS role that the Database Service will assume to access
      # this database.
      assume_role_arn: "arn:aws:iam::123456789012:role/example-role-name"
      # Optional AWS external ID that the Database Service will use to assume
      # a role in an external AWS account.
      external_id: "example-external-id"
      # Redshift-specific configuration.
      redshift:
        # Redshift cluster identifier.
        cluster_id: "redshift-cluster-1"
      # RDS-specific configuration.
      rds:
        # RDS instance identifier.
        instance_id: "rds-instance-1"
        # RDS Aurora cluster identifier.
        cluster_id: "aurora-cluster-1"
      # ElastiCache-specific configuration.
      elasticache:
        # ElastiCache replication group identifier.
        replication_group_id: "elasticache-replication-group-1"
      # MemoryDB-specific configuration.
      memorydb:
        # MemoryDB cluster name.
        cluster_name: "memorydb-cluster-1"

      # Optional AWS Secrets Manager configuration for managing ElastiCache
      # or MemoryDB users.
      #
      # IMPORTANT: please make sure databases sharing the same Teleport-managed
      # users have the same secret_store configuration. The configuration
      # should also be consistent across all Database Services in High
      # Availability (HA) mode.
      secret_store:
        # Prefix to all secrets created by the service. Defaults to 'teleport/'.
        key_prefix: "teleport/"
        # KMS Key ID used for secret encryption and description. If not
        # specified, Secrets Manager uses AWS managed key 'aws/secretsmanager'
        # by default.
        kms_key_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

      # Optional session tags used when assuming IAM roles for DynamoDB access.
      session_tags:
        dynamodb_table_name: "table-a"

    # GCP specific configuration for Cloud SQL and Spanner databases.
    gcp:
      # GCP project ID.
      project_id: "xxx-1234"
      # Cloud SQL instance ID.
      instance_id: "example"

    # Settings specific to Active Directory authentication e.g. for SQL Server.
    ad:
      # Path to Kerberos keytab file.
      keytab_file: /path/to/keytab
      # Active Directory domain name.
      domain: EXAMPLE.COM
      # Service Principal Name to obtain Kerberos tickets for.
      spn: MSSQLSvc/ec2amaz-4kn05du.dbadir.teleportdemo.net:1433
      # Optional path to Kerberos configuration file. Defaults to /etc/krb5.conf.
      krb5_file: /etc/krb5.conf

    # Optional configuration for Azure hosted databases.
    azure:
      # Set is_flexi_server to true when using an Azure flexible server.
      is_flexi_server: false
      # Resource ID for the database in Azure. This field is required for Azure Cache for Redis databases.
      resource_id: "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/example-group/providers/Microsoft.Cache/Redis/example-db-name"

    # Static labels to assign to the database. Used in RBAC.
    static_labels:
      env: "prod"

    # Dynamic labels ("commands"). Used in RBAC.
    dynamic_labels:
    - name: "hostname"
      command: ["hostname"]
      period: 1m0s

Proxy configuration

Self-Hosted

The following Proxy service configuration is relevant for database access:

TLS for database connections

The --insecure-no-tls tsh flag is only supported for MySQL/MariaDB and PostgreSQL connections using a unique port, specified with mysql_public_addr or postgres_public_addr.

proxy_service:
  enabled: "yes"
  # Database proxy is listening on the regular web proxy port.
  web_listen_addr: "0.0.0.0:443"
  # MySQL proxy is listening on a separate port and needs to be enabled
  # on the proxy server.
  mysql_listen_addr: "0.0.0.0:3036"
  # MySQL Server version allows you to overwrite the default Teleport Proxy Service MySQL version (8.0.0-Teleport)
  # Note that if the MySQL client connection is using TLS Routing the dynamic MySQL Server Version takes
  # precedence over the mysql_server_version proxy settings.
  # mysql_server_version: "8.0.4"
  # Postgres proxy listening address. If provided, proxy will use a separate listener
  # instead of multiplexing Postgres protocol on web_listener_addr.
  # postgres_listen_addr: "0.0.0.0:5432"
  # Mongo proxy listening address. If provided, proxy will use a separate listener
  # instead of multiplexing Mongo protocol on web_listener_addr.
  # mongo_listen_addr: "0.0.0.0:27017"
  # By default database clients will be connecting to the Proxy over this
  # hostname. To override public address for specific database protocols
  # use postgres_public_addr and mysql_public_addr.
  public_addr: "teleport.example.com:443"
  # Address advertised to MySQL clients. If not set, public_addr is used.
  mysql_public_addr: "mysql.teleport.example.com:3306"
  # Address advertised to PostgreSQL clients. If not set, public_addr is used.
  postgres_public_addr: "postgres.teleport.example.com:443"
  # Address advertised to Mongo clients. If not set, public_addr is used.
  mongo_public_addr: "mongo.teleport.example.com:443"

Cloud-Hosted

Teleport Enterprise Cloud automatically configures the Teleport Proxy Service with the following settings that are relevant to database access. This reference configuration uses example.teleport.sh in place of your Teleport Enterprise Cloud tenant address:

proxy_service:
  enabled: "yes"
  # Database proxy is listening on the regular web proxy port.
  web_listen_addr: "0.0.0.0:3080"
  # MySQL proxy is listening on a separate port.
  mysql_listen_addr: "0.0.0.0:3036"
  # Database clients will connect to the Proxy Service over this hostname.
  public_addr: "mytenant.teleport.sh:443"
  # Address advertised to MySQL clients.
  mysql_public_addr: "mytenant.teleport.sh:3036"
  # Address advertised to PostgreSQL clients.
  postgres_public_addr: "mytenant.teleport.sh:443"
  # Address advertised to Mongo clients. If not set, public_addr is used.
  mongo_public_addr: "mongo.teleport.example.com:443

Database resource

Full YAML spec of database resources managed by tctl resource commands:

kind: db
version: v3
metadata:
  # Database resource name.
  name: example

  # Database resource description.
  description: "Example database"

  # Database resource static labels.
  labels:
    env: example

spec:
  # Database protocol. Valid options are:
  # "cassandra"
  # "clickhouse"
  # "clickhouse-http"
  # "cockroachdb"
  # "dynamodb"
  # "elasticsearch"
  # "mongodb"
  # "mysql"
  # "oracle"
  # "postgres"
  # "redis"
  # "snowflake"
  # "spanner"
  # "sqlserver"
  protocol: "postgres"

  # Database connection endpoint.
  uri: "localhost:5432"

  # Optional TLS configuration.
  tls:
    # TLS verification mode. Valid options are:
    # 'verify-full' - performs full certificate validation (default).
    # 'verify-ca' - the same as `verify-full`, but skips the server name validation.
    # 'insecure' - accepts any certificate provided by database (not recommended).
    mode: verify-full
    # Optional database DNS server name. It allows to override the DNS name on
    # a client certificate when connecting to a database.
    # Use only with 'verify-full' mode.
    server_name: db.example.com
    # Optional CA for validating the database certificate.
    ca_cert: |
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----
    # Optional configuration that allows Teleport to trust certificate
    # authorities available on the host system. If not set (by default),
    # Teleport only trusts self-signed databases with TLS certificates signed
    # by Teleport's Database Server CA or the ca_cert specified in this TLS
    # setting. For cloud-hosted databases, Teleport downloads the corresponding
    # required CAs for validation.
    trust_system_cert_pool: false

  # Database admin user for automatic user provisioning.
  admin_user:
    # Database admin user name.
    name: "teleport-admin"

  # MySQL only options.
  mysql:
    # The MySQL server version reported by the Teleport Proxy Service.
    # Teleport uses this string when reporting the server version to a 
    # connecting client.
    #
    # When this option is not set, the Database Service will try to connect to
    # a MySQL instance on startup and fetch the server version. Otherwise, 
    # it will use the provided value without connecting to a database. 
    #
    # In both cases, the MySQL server version reported to a client will be 
    # updated on the first successful connection made by a user.
    # Teleport uses that string instead of default '8.0.0-Teleport' version when reporting
    # the server version to a connecting client. When this option is not set, the Database Service will try
    # to connect to MySQL instance on startup and fetch the server version.
    # Otherwise, it will use the provided value without connecting to a database.
    # In both cases MySQL server version reported to a client will be updated on the first successful
    # connection made by a user.
    server_version: 8.0.28

  # Optional AWS configuration for RDS/Aurora/Redshift. Can be auto-detected from the endpoint.
  aws:
    # Region the database is deployed in.
    region: "us-east-1"
    # Optional AWS role that the Database Service will assume to access
    # this database.
    assume_role_arn: "arn:aws:iam::123456789012:role/example-role-name"
    # Optional AWS external ID that the Database Service will use to assume
    # a role in an external AWS account.
    external_id: "example-external-id"
    # Redshift specific configuration.
    redshift:
      # Redshift cluster identifier.
      cluster_id: "redshift-cluster-1"

  # GCP configuration (required for Cloud SQL and Spanner databases).
  gcp:
    # GCP project ID.
    project_id: "xxx-1234"
    # Cloud SQL instance ID.
    instance_id: "example"

  # Settings specific to Active Directory authentication e.g. for SQL Server.
  ad:
    # Path to Kerberos keytab file.
    keytab_file: /path/to/keytab
    # Active Directory domain name.
    domain: EXAMPLE.COM
    # Service Principal Name to obtain Kerberos tickets for.
    spn: MSSQLSvc/ec2amaz-4kn05du.dbadir.teleportdemo.net:1433
    # Optional path to Kerberos configuration file. Defaults to /etc/krb5.conf.
    krb5_file: /etc/krb5.conf

  # Optional dynamic labels.
  dynamic_labels:
  - name: "hostname"
    command: ["hostname"]
    period: 1m0s

You can create a new db resource by running the following commands, which assume that you have created a YAML file called db.yaml with your configuration:

Self-Hosted

# Log in to your cluster with tsh so you can use tctl from your local machine.
# You can also run tctl on your Auth Service host without running "tsh login"
# first.
$ tsh login --proxy=teleport.example.com --user=myuser
# Create the resource
$ tctl create -f db.yaml

Teleport Enterprise Cloud

# Log in to your Teleport cluster so you can use tctl from your local machine.
$ tsh login --proxy=mytenant.teleport.sh --user=myuser
# Create the resource
$ tctl create -f db.yaml