Database Access with Vitess (MySQL protocol)

Teleport can provide secure access to Vitess via the Teleport Database Service. This allows for fine-grained access control through Teleport's RBAC.

In this guide, you will:

1. Configure an Vitess database (MySQL protocol).
2. Join the Vitess database to your Teleport cluster.
3. Connect to the Vitess database via the Teleport Database Service.

How it works

The Teleport Database Service authenticates to your self-hosted Vitess database using mutual TLS. Vitess trusts the Teleport certificate authority for database clients, and presents a certificate signed by either the Teleport database CA or a custom CA. When a user initiates a database session, the Database Service presents a certificate signed by Teleport. The authenticated connection then proxies client traffic from the user.

• Self-Hosted
• Teleport Enterprise Cloud

Prerequisites

• A running Teleport cluster version 15.2.4 or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

• The tctl admin tool and tsh client tool.

  On Teleport Enterprise, you must use the Enterprise version of tctl, which you can download from your Teleport account workspace. Otherwise, visit Installation for instructions on downloading tctl and tsh for Teleport Community Edition.

• A self-hosted Vitess instance.
• A host, e.g., an Amazon EC2 instance, where you will run the Teleport Database Service.
• 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. tctl is supported on macOS and Linux machines. For example:

  tsh login --proxy=teleport.example.com --user=[email protected]
  tctl status
  Cluster  teleport.example.com
  Version  15.2.4
  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.

Step 1/4. Create the Teleport Database Token

The Database Service requires a valid auth token to connect to the cluster. Generate one by running the following command against your Teleport Auth Service and save it in /tmp/token on the node that will run the Database Service:

tctl tokens add --type=db

Step 2/4. Create a certificate/key pair

Teleport uses mutual TLS authentication with self-hosted databases. These databases must be configured with Teleport's certificate authority to be able to verify client certificates. They also need a certificate/key pair that Teleport can verify.

If you are using Teleport Cloud, your Teleport user must be allowed to impersonate the system role Db in order to be able to generate the database certificate.

Include the following allow rule in in your Teleport Cloud user's role:

allow:
  impersonate:
    users: ["Db"]
    roles: ["Db"]

From your local workstation, create the secrets:

Export Teleport's certificate authority and generate certificate/key pair
for host db.example.com with a 3-month validity period.
tctl auth sign --format=db --host=db.example.com --out=server --ttl=2190h

In this example, db.example.com is the hostname where the Teleport Database Service can reach the Vitess server.

The command will create 3 files: server.cas, server.crt and server.key which you'll need to enable mutual TLS.

Step 3/4. Configure Vitess

---
apiVersion: v1
kind: Secret
metadata:
  name: example-cluster-config
type: Opaque
stringData:
  server.cas: |
    -----BEGIN CERTIFICATE-----
    MIIDlDCCAnygAwIBAgIQcCge3zdTWnA7isWitaG5yzANBgkqhkiG9w0BAQsFADBk
    ...
    jtOP8B0/0xc=
    -----END CERTIFICATE-----
  server.crt: |
    -----BEGIN CERTIFICATE-----
    MIIDqjCCApKgAwIBAgIRAKq0OQqYIx3pbkSVpIgMooowDQYJKoZIhvcNAQELBQAw
    ...
    aRWuAdb7KYfHgZgC+k5jiFS9MYPbOc3qMK6KwGAU
    -----END CERTIFICATE-----
  server.key: |
    -----BEGIN RSA PRIVATE KEY-----
    MIIEpQIBAAKCAQEAsiejNWoNPPgcjjNZvG0pA+eADXxPyiGf6Or7oiy2ZmkblC4I
    ...
    hr6KW+m+bBx0ABXrJVZ4dfv7ppP173vhavmSG3dvo2D5savAay6L/bE=
    -----END RSA PRIVATE KEY-----

cells:
  - name: zone1
    gateway:
      extraFlags:
        mysql_auth_server_impl: clientcert
      secureTransport:
        required: true
        tls:
          clientCACertSecret:
            name: teleport-cluster-config
            key: server.cas
          certSecret:
            name: teleport-cluster-config
            key: server.crt
          keySecret:
            name: teleport-cluster-config
            key: server.key

vtgate ...                                      \
    --mysql_server_ssl_ca=/path/to/server.cas   \
    --mysql_server_ssl_cert=/path/to/server.crt \
    --mysql_server_ssl_key=/path/to/server.key  \
    --mysql_auth_server_impl=clientcert

Create a Teleport user

tctl users add \  --roles=access \  --db-users=\* \  --db-names=\* \  alice

tctl users add \  --roles=access,requester \  --db-users=\* \  --db-names=\* \  alice

For more detailed information about database access controls and how to restrict access see RBAC documentation.

Configure and Start the Database Service

Install and configure Teleport where you will run the Teleport Database Service:

helm repo add teleport https://charts.releases.teleport.dev

helm repo update

Step 4/4. Connect

Once the Database Service has joined the cluster, log in to see the available databases:

tsh login --proxy=teleport.example.com --user=alice
tsh db ls
Name           Description    Labels
-------------- -------------- --------
example-vitess Example Vitess env=dev

tsh login --proxy=mytenant.teleport.sh --user=alice
tsh db ls
Name           Description    Labels
-------------- -------------- --------
example-vitess Example Vitess env=dev

Note that you will only be able to see databases your role has access to. See the RBAC guide for more details.

To retrieve credentials for a database and connect to it:

tsh db connect example-vitess

You can optionally specify the database name and the user to use by default when connecting to the database instance:

tsh db connect --db-user=root --db-name=mysql example-vitess

To log out of the database and remove credentials:

Remove credentials for a particular database instance.
tsh db logout example-vitess
Remove credentials for all database instances.
tsh db logout