[v13] [docs] GCP MySQL IAM authentication support (#39130)

* [docs] GCP MySQL IAM authentication support

* review comments

* remove legacy OTP flow

* address review comments

docs/pages/database-access/guides/mysql-cloudsql.mdx

@@ -24,12 +24,38 @@ description: How to configure Teleport database access with GCP Cloud SQL MySQL.
   Service
 - (!docs/pages/includes/tctl.mdx!)
 
-## Step 1/5. Create a service account for the Teleport Database Service
+## Step 1/7. Enable Cloud SQL IAM authentication
 
-Teleport uses one-time passwords to authenticate with Cloud SQL MySQL. To be
-able to authenticate with a database instance, Teleport must run as a service
-account that has a few of the "Cloud SQL Admin" role permissions. You can create
-a new service account or modify an existing one to add required permissions.
+Teleport uses [IAM
+authentication](https://cloud.google.com/sql/docs/mysql/iam-authentication)
+with Cloud SQL MySQL instances.
+
+(!docs/pages/includes/database-access/cloudsql_enable_iam_auth.mdx type="MySQL" !)
+
+## Step 2/7. Create a service account for a database user
+
+Teleport uses service accounts to connect to Cloud SQL databases.
+
+(!docs/pages/includes/database-access/cloudsql_create_db_user_account.mdx!)
+
+(!docs/pages/includes/database-access/cloudsql_grant_db_user.mdx!)
+
+### Configure authentication for your service account
+
+Now go back to the Users page of your Cloud SQL instance and add a new user
+account. In the sidebar, choose "Cloud IAM" authentication type and add the
+service account you've just created:
+
+![Add Cloud SQL User Account](../../../img/database-access/guides/cloudsql/[email protected])
+
+Press "Add". See [Creating and managing IAM
+users](https://cloud.google.com/sql/docs/mysql/add-manage-iam-users) in Google
+Cloud documentation for more info.
+
+## Step 3/7. Create a service account for the Teleport Database Service
+
+The final part of GCP configuration is to create a service account for the
+Teleport Database Service.
 
 ### Create a service account
 
@@ -41,20 +67,18 @@ page and create another service account:
 
 ### Grant permissions
 
-Assign the Service Account the "Cloud SQL Admin" role:
-
-![Grant Cloud SQL Admin to Service Account](../../../img/database-access/guides/cloudsql/[email protected])
+(!docs/pages/includes/database-access/cloudsql_grant_db_service_account.mdx!)
 
 <Admonition type="note" title="Service account permissions">
-  The default "Cloud SQL Admin" IAM role includes more permissions than the
-  Database Service needs to generate one-time user passwords. To further restrict
-  the service account, you can create a role that includes only the following
-  permissions:
+  "Service Account Token Creator", "Cloud SQL Viewer", and "Cloud SQL Admin"
+  IAM roles include more permissions than the Database Service needs. To further
+  restrict the service account, you can create a role that includes only the
+  following permissions:
   ```ini
-  # Used to download a list of database users.
-  cloudsql.users.list
-  # Used to update a user with a one-time password.
-  cloudsql.users.update
+  # Used to generate IAM auth tokens when connecting to a database instance.
+  iam.serviceAccounts.getAccessToken
+  # Used to check database user type.
+  cloudsql.users.get
   # Used to auto-download the instance's root CA certificate.
   cloudsql.instances.get
   ```
@@ -70,20 +94,11 @@ instead of the default `3306` as the default Cloud SQL MySQL listener does not
 trust generated ephemeral certificates. For this reason, you should make sure
 to allow port `3307` when using "Allow only SSL connections" with MySQL.
 
-### Create a key for the service account
-
-Once created, go to that service account's Keys tab and create a new key:
-
-![Service Account Keys](../../../img/database-access/guides/cloudsql/[email protected])
-
-Make sure to choose JSON format:
+### (Optional) Create a key for the service account
 
-![Service Account New Key](../../../img/database-access/guides/cloudsql/[email protected])
+(!docs/pages/includes/database-access/cloudsql_service_account_key.mdx!)
 
-Save the file. Your Teleport Database Service will need to use it as GCP
-application credentials file.
-
-## Step 2/5. Gather Cloud SQL instance information
+## Step 4/7. Gather Cloud SQL instance information
 
 To connect a Cloud SQL database to Teleport, you'll need to gather a few pieces
 of information about the instance.
@@ -106,28 +121,22 @@ on the "Connect to this instance" panel on the Overview page:
 
 ![Instance Public IP](../../../img/database-access/guides/cloudsql/[email protected])
 
-- Cloud SQL instance root certificate.
+- (Optional) Cloud SQL instance root certificate.
+
+(!docs/pages/includes/database-access/cloudsql_download_root_ca.mdx!)
 
-The instance's root certificate is required so Teleport can validate the
-certificate presented by the database instance. You can download `server-ca.pem`
-file from the Connections tab under Security section:
+## Step 5/7. Create a Teleport user
 
-![Instance Root Certificate](../../../img/database-access/guides/cloudsql/[email protected])
+(!docs/pages/includes/database-access/create-user.mdx!)
 
-## Step 3/5. Set up the Teleport Database Service
+## Step 6/7. Set up the Teleport Database service
 
 (!docs/pages/includes/database-access/token.mdx!)
 
 Install Teleport on the host where you will run the Teleport Database Service:
 
 (!docs/pages/includes/install-linux.mdx!)
 
-### Create a user
-
-(!docs/pages/includes/database-access/create-user.mdx!)
-
-## Step 4/5. Set up the Teleport Database service
-
 Below is an example of a Database Service configuration file that proxies
 a single Cloud SQL MySQL database. Save this file as `/etc/teleport.yaml`:
 
@@ -137,12 +146,12 @@ a single Cloud SQL MySQL database. Save this file as `/etc/teleport.yaml`:
 ```yaml
 version: v3
 teleport:
-  data_dir: /var/lib/teleport-db
+  data_dir: /var/lib/teleport
   nodename: test
   # Proxy address to connect to. Note that it has to be the proxy address
   # because the Database Service always connects to the cluster over a reverse
   # tunnel.
-  proxy_server: teleport.example.com:3080
+  proxy_server: teleport.example.com:443
   auth_token: "/tmp/token"
 db_service:
   enabled: "yes"
@@ -157,7 +166,8 @@ db_service:
     protocol: "mysql"
     # Database endpoint. For Cloud SQL use instance's public IP address.
     uri: "35.1.2.3:3306"
-    # Path to Cloud SQL instance root certificate you downloaded above.
+    # (Optional) path to Cloud SQL instance root certificate you downloaded
+    # manually above.
     ca_cert_file: /path/to/cloudsql/instance/root.pem
     # GCP-specific configuration when connecting a Cloud SQL instance.
     gcp:
@@ -182,7 +192,7 @@ proxy_service:
 ```yaml
 version: v3
 teleport:
-  data_dir: /var/lib/teleport-db
+  data_dir: /var/lib/teleport
   nodename: test
   # Proxy address to connect to. Use your Teleport Cloud tenant address.
   proxy_server: mytenant.teleport.sh:443
@@ -200,7 +210,8 @@ db_service:
     protocol: "mysql"
     # Database endpoint. For Cloud SQL use instance's public IP address.
     uri: "35.1.2.3:3306"
-    # Path to Cloud SQL instance root certificate you downloaded above.
+    # (Optional) path to Cloud SQL instance root certificate you downloaded
+    # manually above.
     ca_cert_file: /path/to/cloudsql/instance/root.pem
     # GCP-specific configuration when connecting a Cloud SQL instance.
     gcp:
@@ -236,19 +247,9 @@ proxy_service:
 
 ### GCP credentials
 
-The Teleport Database Service must have the credentials of `teleport-db-service` GCP
-service account we created
-[above](#step-15-create-a-service-account-for-the-teleport-database-service) in order to
-be able to log in.
-
-The easiest way to ensure that is to set the `GOOGLE_APPLICATION_CREDENTIALS`
-environment variable to point to the JSON credentials file you downloaded
-earlier.
+(!docs/pages/includes/database-access/cloudsql_service_credentials.mdx!)
 
-See [Authenticating as a service account](https://cloud.google.com/docs/authentication/production)
-in the Google Cloud documentation for more details.
-
-## Step 5/5. Connect
+## Step 7/7. Connect
 
 Once the Database Service has joined the cluster, log in to see the available
 databases:
@@ -285,12 +286,18 @@ our [RBAC](../rbac.mdx) guide for more details.
 To retrieve credentials for a database and connect to it:
 
 ```code
-$ tsh db connect --db-user=alice --db-name=mysql cloudsql
+$ tsh db connect --db-user=teleport --db-name=mysql cloudsql
 ```
 
-<Admonition type="note" title="Note">
-  The `mysql` command-line client should be available in PATH in order to be
-  able to connect.
+<Admonition
+  type="note"
+  title="What database user name to use?"
+>
+
+When connecting to the database, use either the database user name or the
+service account's Email ID. Both the user name and the service account's Email
+ID are shown on the Users page of your Cloud SQL instance.
+
 </Admonition>
 
 To log out of the database and remove credentials:
@@ -302,3 +309,29 @@ $ tsh db logout cloudsql
 $ tsh db logout
 ```
 
+## Troubleshooting
+
+### Error when connecting to a replica instance
+
+You may encounter the following error when connecting to a replica instance:
+
+```code
+$ tsh db connect --db-user root -n test cloudsql-replica 
+ERROR 1105 (HY000): Could not update Cloud SQL user "<username>" password:
+
+  The requested operation is not valid for a replica instance.
+
+...
+```
+
+Connecting as built-in database users with passwords are not supported for
+Cloud SQL replica instances. Please follow this guide to use IAM authentication
+instead.
+
+## Next steps
+
+(!docs/pages/includes/database-access/guides-next-steps.mdx!)
+
+- Learn more about [authenticating as a service
+  account](https://cloud.google.com/docs/authentication#service-accounts) in
+  Google Cloud.