Add Vitess guide (MySQL protocol) (#35650)

* Add Vitess guide (MySQL protocol) * Update cspell
2026-10-28 03:19:47 +08:00 · 2023-12-13 11:57:22 +00:00
parent 916a2e5700
commit 71fd30e251
6 changed files with 237 additions and 1 deletions
@@ -1263,6 +1263,10 @@
            {
              "title": "Snowflake",
              "slug": "/database-access/guides/snowflake/"
+            },
+            {
+              "title": "Vitess (MySQL protocol)",
+              "slug": "/database-access/guides/vitess/"
            }
          ]
        },
@@ -874,7 +874,10 @@
    "yubishm",
    "znmqk",
    "zxvf",
-    "zztop"
+    "zztop",
+    "Vitess",
+    "vtgate",
+    "clientcert"
  ],
  "flagWords": ["hte"]
 }
@@ -0,0 +1,228 @@
+---
+title: Database Access with Vitess (MySQL protocol)
+description: How to configure Teleport database access for Vitess (MySQL protocol)
+---
+
+(!docs/pages/includes/database-access/db-introduction.mdx dbType="Vitess (MySQL)" dbConfigure="Vitess database (MySQL protocol) with mutual TLS authentication" dbName="Vitess" !)
+
+<Tabs>
+<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">
+![Teleport Database Access Vitess Self-Hosted](../../../img/database-access/guides/vitess_selfhosted.png)
+</TabItem>
+<TabItem scope={["cloud"]} label="Teleport Enterprise Cloud">
+![Teleport Database Access Vitess Cloud](../../../img/database-access/guides/vitess_cloud.png)
+</TabItem>
+
+</Tabs>
+
+<Notice type="note">
+  Accessing Vitess using the gRPC protocol is not currently supported by
+  Teleport.
+</Notice>
+
+## Prerequisites
+
+(!docs/pages/includes/edition-prereqs-tabs.mdx!)
+
+- A self-hosted Vitess instance.
+- A host, e.g., an Amazon EC2 instance, where you will run the Teleport Database
+  Service.
+- (!docs/pages/includes/tctl.mdx!)
+
+## Step 1/4. Create the Teleport Database Token
+
+(!docs/pages/includes/database-access/token.mdx!)
+
+## Step 2/4. Create a certificate/key pair
+
+(!docs/pages/includes/database-access/tctl-auth-sign.mdx!)
+
+From your local workstation, create the secrets:
+
+```code
+# 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.
+
+(!docs/pages/includes/database-access/ttl-note.mdx!)
+
+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
+
+<Tabs>
+<TabItem label="Kubernetes operator">
+If you are running your Vitess cluster using a [Vitess Operator for Kubernetes](https://vitess.io/docs/18.0/get-started/operator/),
+as a first step copy the contents of files `server.cas`, `server.crt` and `server.key` into a secret containing the cluster configuration.
+
+```yaml
+---
+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-----
+```
+
+Next, update the gateway configuration:
+
+- Add a new `extraFlags` section with a new entry `mysql_auth_server_impl: clientcert`.
+- Add a new `secureTransport` section referencing the added files.
+
+```yaml
+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
+```
+
+</TabItem>
+<TabItem label="Custom deployment">
+If you are running your Vitess cluster using a custom deployment, you will need to update the flags for the `vtgate` service. The following flags needs to be added:
+
+```
+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
+```
+
+The files `server.cas`, `server.crt` and `server.key` mut be in a location
+accessible by the `vtgate` service.
+
+For more details about `vtgate` and Vitess configuration, please see the
+[documentation](https://vitess.io/docs/18.0/user-guides/configuration-basic/vtgate/).
+
+</TabItem>
+</Tabs>
+
+### Create a Teleport user
+
+(!docs/pages/includes/database-access/create-user.mdx!)
+
+### Configure and Start the Database Service
+
+Install and configure Teleport where you will run the Teleport Database Service:
+
+<Tabs>
+<TabItem label="Linux Server">
+
+(!docs/pages/includes/install-linux.mdx!)
+
+(!docs/pages/includes/database-access/db-configure-start.mdx
+dbName="example-vitess" dbProtocol="mysql"
+databaseAddress="db.example.com:3306" !)
+
+</TabItem>
+<TabItem label="Kubernetes Cluster">
+  Teleport provides Helm charts for installing the Teleport Database Service in Kubernetes Clusters.
+
+(!docs/pages/kubernetes-access/helm/includes/helm-repo-add.mdx!)
+
+(!docs/pages/includes/database-access/db-helm-install.mdx dbName="example-vitess"
+dbProtocol="mysql" databaseAddress="db.example.com:3306" !)
+
+</TabItem>
+</Tabs>
+
+(!docs/pages/includes/database-access/multiple-instances-tip.mdx !)
+
+## Step 4/4. Connect
+
+Once the Database Service has joined the cluster, log in to see the available
+databases:
+
+<Tabs>
+<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">
+
+```code
+$ tsh login --proxy=teleport.example.com --user=alice
+$ tsh db ls
+# Name           Description    Labels
+# -------------- -------------- --------
+# example-vitess Example Vitess env=dev
+```
+
+</TabItem>
+<TabItem scope={["cloud"]} label="Teleport Enterprise Cloud">
+
+```code
+$ tsh login --proxy=mytenant.teleport.sh --user=alice
+$ tsh db ls
+# Name           Description    Labels
+# -------------- -------------- --------
+# example-vitess Example Vitess env=dev
+```
+
+</TabItem>
+
+</Tabs>
+
+Note that you will only be able to see databases your role has access to. See
+the [RBAC](../rbac.mdx) guide for more details.
+
+To retrieve credentials for a database and connect to it:
+
+```code
+$ 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:
+
+```code
+$ tsh db connect --db-user=root --db-name=mysql example-vitess
+```
+
+<Admonition type="note" title="Note">
+  The `mysql` or `mariadb` command-line client should be available in `PATH` in
+  order to be able to connect. `mariadb` is a default command-line client for
+  MySQL and MariaDB.
+</Admonition>
+
+To log out of the database and remove credentials:
+
+```code
+# Remove credentials for a particular database instance.
+$ tsh db logout example-vitess
+# Remove credentials for all database instances.
+$ tsh db logout
+```
@@ -29,6 +29,7 @@
 - [Self-Hosted Cassandra & ScyllaDB](../../database-access/guides/cassandra-self-hosted.mdx): Connect self-hosted Cassandra or ScyllaDB.
 - [Self-Hosted Oracle](../../database-access/guides/oracle-self-hosted.mdx): Connect self-hosted Oracle database.
 - [Snowflake](../../database-access/guides/snowflake.mdx): Connect Snowflake.
+- [Vitess](../../database-access/guides/vitess.mdx): Connect Vitess.

 ## Other guides