Fork me on GitHub

Teleport

Database Access Configuration Reference

Improve

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

  # Matchers for registering AWS-hosted databases.
  aws:
    # Database types. Valid options are:
    # 'rds' - discovers and registers AWS RDS and Aurora databases.
    # 'redshift' - discovers and registers AWS Redshift databases.
    # 'elasticache' - discovers and registers AWS ElastiCache Redis databases.
    # 'memorydb' - discovers and registers AWS MemoryDB Redis databases.
  - types: ["rds", "redshift", "elasticache", "memorydb"]
    # AWS regions to register databases from.
    regions: ["us-west-1", "us-east-2"]
    # 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 single-server databases.
    # 'postgres' - discovers and registers Azure PostgreSQL single-server databases.
    # 'redis' - discovers and registers Azure Cache for Redis databases.
  - types: ["mysql", "postgres", "redis"]
    # 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. Can be: "postgres", "mysql", "mongodb", "cockroachdb", "sqlserver", or "redis".
    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

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

    # GCP specific configuration for Cloud SQL 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

    # 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

The following Proxy service configuration is relevant for Database Access:

Proxy TLS Warning for PostgreSQL

The PostgreSQL connection requires TLS enabled for the SSL connection that operates on the web_listen_addr. Do not set --insecure-no-tls for the proxy Teleport instances as a parameter. If you are terminating TLS at a Application Load Balancer (ALB) or other service that may require enabling a backend protocol of HTTPS for the target address.

proxy_service:
  enabled: "yes"
  # PostgreSQL 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 and needs to be enabled
  # on the proxy server.
  mysql_listen_addr: "0.0.0.0:3036"
  # 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:3080"
  # 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"

Teleport Cloud automatically configures the Teleport Proxy Service with the following settings that are relevant to Database Access. This reference configuration uses mytenant.teleport.sh in place of your Teleport Cloud tenant address.

proxy_service:
  enabled: "yes"
  # PostgreSQL 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"

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.
  protocol: "postgres"

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

  # Optional CA for validating the database certificate.
  ca_cert: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----

  # 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"
    # Redshift specific configuration.
    redshift:
      # Redshift cluster identifier.
      cluster_id: "redshift-cluster-1"

  # Optional GCP configuration for Cloud SQL.
  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:

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