이 가이드는 Teleport 사용자와 보호된 데이터베이스 간의 사용자 트래픽을 프록시하는 Teleport 데이터베이스 서비스의 구성 옵션을 설명합니다.

데이터베이스 서비스 구성#

다음 스니펫은 teleport.yaml 구성 파일에 포함된 데이터베이스 서비스의 전체 YAML 구성을 보여줍니다:

<!-- INCLUDE:ENGLISH:docs/pages/includes/config-reference/database-config.yaml -->
db_service:
  # Enables the Database Service.
  enabled: true

  # Matchers for database resources created with "tctl create" command or by the
  # discovery service.
  resources:
    # Resource labels to match.
    #
    # Use specific label selectors so each Database Service instance only
    # matches databases it can actually reach.
  - labels:
      "env": "staging"
    # 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 by performing auto-discovery
  # on the Database Service.
  #
  # NOTE: for most deployments, it is recommended to use the Discovery Service
  # to register AWS databases instead of Database Service–based discovery.
  aws:
    # Database types. Valid options are:
    # 'rds' - discovers and registers Amazon RDS and Aurora databases.
    # 'rdsproxy' - discovers and registers Amazon RDS Proxy databases.
    # 'redshift' - discovers and registers Amazon Redshift databases.
    # 'redshift-serverless' - discovers and registers Amazon Redshift Serverless databases.
    # 'elasticache' - discovers and registers Amazon ElastiCache Redis and Valkey databases.
    # 'elasticache-serverless' - Amazon ElastiCache Serverless Redis or Valkey databases.
    # 'memorydb' - discovers and registers Amazon MemoryDB databases.
    # 'opensearch' - discovers and registers Amazon OpenSearch databases.
    # 'docdb' - discovers and registers Amazon DocumentDB databases.
  - types: ["rds", "rdsproxy","redshift", "redshift-serverless", "elasticache", "elasticache-serverless", "memorydb", "opensearch", "docdb"]
    # 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.
    #
    # Use specific tag selectors so each Database Service instance only matches
    # databases it can actually reach.
    tags:
      "env": "staging"

  # Matchers for registering Azure-hosted databases by performing auto-discovery
  # on the Database Service.
  #
  # NOTE: for most deployments, it is recommended to use the Discovery Service
  # to register AWS databases instead of Database Service–based discovery.
  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.
    #
    # Use specific tag selectors so each Database Service instance only matches
    # databases it can actually reach.
    tags:
      "env": "staging"

  # 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

    # Oracle only options.
    oracle:
      # Randomize host order per connection attempt to spread load. Optional.
      shuffle_hostnames: true
      # Retries per host on network errors only; non-network errors stop (default: 2). Optional.
      retry_count: 5            

    # 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"
      # AlloyDB-specific configuration.
      alloydb:
        # Endpoint type. Valid types: "private" (default), "public", "PSC".
        endpoint_type: "private"
        # Endpoint override. IP address or hostname to be used instead of automatically resolved endpoint.
        endpoint_override: "11.22.33.44"

    # 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
      # Name of the service account Teleport uses to perform LDAP queries for retrieving user SIDs.
      ldap_service_account_name: "svc-teleport"
      # SID of the above service account. Teleport uses this to authenticate LDAP queries.
      # Also required for PKINIT if the user SID must be included in the certificate.
      ldap_service_account_sid: "S-1-5-21-1111111111-2222222222-3333333333-4444"

    # 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
<!-- /INCLUDE:ENGLISH -->

프록시 구성#

proxy_service:
  enabled: true
  # 데이터베이스 프록시는 일반 웹 프록시 포트에서 수신합니다.
  web_listen_addr: "0.0.0.0:443"
  # MySQL 프록시는 별도의 포트에서 수신하며 프록시 서버에서
  # 활성화해야 합니다.
  mysql_listen_addr: "0.0.0.0:3036"
  # MySQL 서버 버전을 통해 기본 Teleport 프록시 서비스 MySQL 버전(8.0.0-Teleport)을 덮어쓸 수 있습니다.
  # MySQL 클라이언트 연결이 TLS 라우팅을 사용하는 경우, 동적 MySQL 서버 버전이
  # mysql_server_version 프록시 설정보다 우선합니다.
  # mysql_server_version: "8.0.4"
  # Postgres 프록시 수신 주소. 제공된 경우, 프록시는 web_listener_addr에서
  # Postgres 프로토콜을 멀티플렉싱하는 대신 별도의 리스너를 사용합니다.
  # postgres_listen_addr: "0.0.0.0:5432"
  # Mongo 프록시 수신 주소. 제공된 경우, 프록시는 web_listener_addr에서
  # Mongo 프로토콜을 멀티플렉싱하는 대신 별도의 리스너를 사용합니다.
  # mongo_listen_addr: "0.0.0.0:27017"
  # 기본적으로 데이터베이스 클라이언트는 이 호스트명을 통해 프록시에 연결합니다.
  # 특정 데이터베이스 프로토콜의 공개 주소를 재정의하려면
  # postgres_public_addr 및 mysql_public_addr을 사용하세요.
  public_addr: "teleport.example.com:443"
  # MySQL 클라이언트에 광고되는 주소. 설정되지 않은 경우 public_addr을 사용합니다.
  mysql_public_addr: "mysql.teleport.example.com:3306"
  # PostgreSQL 클라이언트에 광고되는 주소. 설정되지 않은 경우 public_addr을 사용합니다.
  postgres_public_addr: "postgres.teleport.example.com:443"
  # Mongo 클라이언트에 광고되는 주소. 설정되지 않은 경우 public_addr을 사용합니다.
  mongo_public_addr: "mongo.teleport.example.com:443"

proxy_service:
  enabled: true
  # 데이터베이스 프록시는 일반 웹 프록시 포트에서 수신합니다.
  web_listen_addr: "0.0.0.0:3080"
  # MySQL 프록시는 별도의 포트에서 수신합니다.
  mysql_listen_addr: "0.0.0.0:3036"
  # 데이터베이스 클라이언트는 이 호스트명을 통해 프록시 서비스에 연결합니다.
  public_addr: "mytenant.teleport.sh:443"
  # MySQL 클라이언트에 광고되는 주소.
  mysql_public_addr: "mytenant.teleport.sh:3036"
  # PostgreSQL 클라이언트에 광고되는 주소.
  postgres_public_addr: "mytenant.teleport.sh:443"
  # Mongo 클라이언트에 광고되는 주소. 설정되지 않은 경우 public_addr을 사용합니다.
  mongo_public_addr: "mongo.teleport.example.com:443"

데이터베이스 리소스#

tctl 리소스 명령으로 관리되는 데이터베이스 리소스의 전체 YAML 스펙:

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

  # Oracle only options.
  oracle:
    # Randomize host order per connection attempt to spread load. Optional.
    shuffle_hostnames: true
    # Retries per host on network errors only; non-network errors stop (default: 2). Optional.
    retry_count: 5            

  # 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

다음 명령을 실행하여 새 db 리소스를 생성할 수 있습니다. 이 명령은 구성이 포함된 db.yaml이라는 YAML 파일을 생성했다고 가정합니다:

# 로컬 머신에서 tctl을 사용할 수 있도록 tsh로 클러스터에 로그인합니다.
# "tsh login"을 먼저 실행하지 않고 Auth Service 호스트에서 tctl을 실행할 수도 있습니다.
$ tsh login --proxy=teleport.example.com --user=myuser
# 리소스 생성
$ tctl create -f db.yaml

# 로컬 머신에서 tctl을 사용할 수 있도록 Teleport 클러스터에 로그인합니다.
$ tsh login --proxy=mytenant.teleport.sh --user=myuser
# 리소스 생성
$ tctl create -f db.yaml