-
Notifications
You must be signed in to change notification settings - Fork 168
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
b/383645460 Extend documentation to cover Cloud SQL (#1596)
- Add instructions to deploy a Cloud SQL Auth Proxy VM - Add separate page for MySQL, PostgreSQL
- Loading branch information
Showing
10 changed files
with
310 additions
and
67 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,156 @@ | ||
| # Access MySQL, MariaDB, or PostgreSQL | ||
|
|
||
| ???+ info "Required roles" | ||
|
|
||
| To follow the steps in this guide, you need the following roles: | ||
|
|
||
| * [ ] [Compute Viewer :octicons-link-external-16:](https://cloud.google.com/compute/docs/access/iam) on the project. | ||
| * [ ] [IAP-Secured Tunnel User :octicons-link-external-16:](https://cloud.google.com/iap/docs/managing-access#roles) on | ||
| the project or VM. | ||
|
|
||
| ???+ success "Prerequisites" | ||
|
|
||
| To follow the steps in this guide, make sure that you meet the following prerequisites: | ||
|
|
||
| * You downloaded and installed a database client such as MySQL Shell, PostgreSQL Shell, or pgAdmin on your | ||
| local computer. | ||
| * You [created a firewall rule](setup-iap.md) that allows IAP to connect to port <code>3306</code> (MySQL, MariaDB) | ||
| or port <code>5432</code> (PostgreSQL) of the database VM. | ||
|
|
||
| You can use IAP Desktop to access MySQL, MariaDB, or PostgreSQL in two ways: | ||
|
|
||
| 1. You can let IAP Desktop launch and [connect the database client](#connect-a-client-application) | ||
| for you. IAP Desktop automatically establishes an | ||
| [IAP TCP forwarding tunnel :octicons-link-external-16:](https://cloud.google.com/iap/docs/using-tcp-forwarding) | ||
| and keeps the tunnel open until you close the client application. | ||
|
|
||
| This is the most convenient option, but it only works for client applications that allow | ||
| connection details (server name, port number) to be passed as a command line parameter. These include | ||
| the command-line clients for MySQL, MariaDB, and PostgreSQL, but not MySQL Workbench or pgAdmin. | ||
|
|
||
| 1. You can let IAP Desktop [open a tunnel](#open-a-tunnel). You can then use any tool to | ||
| connect to that tunnel and the tunnel remains open until you close IAP Desktop. | ||
|
|
||
| This option is slightly less convenient, but works with most client applications, including MySQL Workbench and pgAdmin. | ||
|
|
||
| The way IAP Desktop uses IAP-TCP to connect to MySQL, MariaDB, or PostgreSQL differs depending on | ||
| whether you're running the database on Compute Engine or using Cloud SQL: | ||
|
|
||
| === "Compute Engine" | ||
|
|
||
| If you're running MySQL, MariaDB, or PostgreSQL on Compute Engine, you don't need any additional VM to | ||
| let IAP Desktop connect to the database. The only prerequisite is | ||
| [a firewall rule](setup-iap.md) that allows IAP-TCP to connect to | ||
| port <code>3306</code> (MySQL, MariaDB) | ||
| or port <code>5432</code> (PostgreSQL) of the database VM. | ||
|
|
||
|  | ||
|
|
||
| === "Cloud SQL" | ||
|
|
||
| If you're using Cloud SQL for MySQL or PostgreSQL, you need an additional VM that runs the | ||
| [Cloud SQL Auth Proxy :octicons-link-external-16:](https://cloud.google.com/sql/docs/mysql/sql-proxy). This VM is necessary | ||
| because IAP-TCP doesn't support creating tunnels to managed services such as Cloud SQL. | ||
|
|
||
|  | ||
|
|
||
| To deploy a Cloud SQL Auth Proxy VM, see [Set up a Cloud SQL Proxy VM](setup-cloudsql.md). | ||
|
|
||
|
|
||
| ## Connect the database client | ||
|
|
||
| To launch and connect a client application automatically, do the following: | ||
|
|
||
| === "MySQL Shell" | ||
|
|
||
| 1. In the **Project Explorer** tool window, right-click your database VM and select | ||
| **Connect client application > MySQL Shell**. | ||
| { width="400" } | ||
| !!! note | ||
| If you don't see the menu entry, then IAP Desktop wasn't able to | ||
| find a supported version of the MySQL command-line client on your computer. | ||
|
|
||
| 1. IAP Desktop now creates an [IAP TCP forwarding tunnel :octicons-link-external-16:](https://cloud.google.com/iap/docs/using-tcp-forwarding) and | ||
| launches the MySQL command-line client. | ||
|
|
||
| === "PostgreSQL Shell" | ||
|
|
||
| 1. In the **Project Explorer** tool window, right-click your database VM and select | ||
| **Connect client application > PostgreSQL Shell**. | ||
| !!! note | ||
| If you don't see the menu entry, then IAP Desktop wasn't able to | ||
| find a supported version of the PostgreSQL command-line client on your computer. | ||
|
|
||
| 1. IAP Desktop now creates an [IAP TCP forwarding tunnel :octicons-link-external-16:](https://cloud.google.com/iap/docs/using-tcp-forwarding) and | ||
| launches the PostgreSQL command-line client. | ||
|
|
||
| === "Custom" | ||
|
|
||
| You can register additional database clients by | ||
| [creating an IAP Application Protocol Configuration (IAPC)](client-application-configuration.md). | ||
|
|
||
|
|
||
| ## Open a tunnel | ||
|
|
||
| You can let IAP Desktop open a tunnel and connect to tha tunnel by doing the following: | ||
|
|
||
| === "MySQL Workbench" | ||
|
|
||
| 1. In the **Project Explorer** tool window, right-click your database VM and select | ||
| **Tunnel to > MySQL/MariaDB**. | ||
|
|
||
| { width="400" } | ||
|
|
||
| A notification appears: | ||
|
|
||
| { width="300" } | ||
|
|
||
| 1. Launch MySQL Workbench. | ||
| 1. In MySQL Workbench, go to **Database > Connect to database**. | ||
| 1. In the **Connect to database** dialog, configure the following: | ||
|
|
||
| * **Hostname**: `127.0.0.1` | ||
| * **Port**: Enter the port number indicated in the notification. | ||
|
|
||
| 1. Click **OK**. | ||
|
|
||
|
|
||
| === "pgAdmin" | ||
|
|
||
| 1. In the **Project Explorer** tool window, right-click your database VM and select | ||
| **Tunnel to > PostgreSQL**. | ||
|
|
||
| A notification appears: | ||
|
|
||
| { width="300" } | ||
|
|
||
| 1. Launch pgAdmin. | ||
| 1. Click **Add new server**. | ||
| 1. In the **Register server** dialog, enter a name for the server. | ||
| 1. Switch to the **Connection** tab and configure the following: | ||
|
|
||
| * **Host name/address**: `127.0.0.1` | ||
| * **Port**: Enter the port number indicated in the notification. | ||
|
|
||
| 1. Click **Save**. | ||
|
|
||
| === "Custom" | ||
|
|
||
| You can register additional database clients by | ||
| [creating an IAP Application Protocol Configuration (IAPC)](client-application-configuration.md). | ||
|
|
||
|
|
||
| To view all active tunnels and their port numbers, select **View > Active IAP tunnels** in the main menu. | ||
|
|
||
|
|
||
| !!! note | ||
|
|
||
| When you open a tunnel to the same VM again in the future, IAP Desktop | ||
| will use the same port number unless it's in use by a different application. | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,108 @@ | ||
| # Set up a Cloud SQL Proxy VM | ||
|
|
||
|
|
||
| ???+ info "Required roles" | ||
|
|
||
| To follow the steps in this guide, you need the following roles: | ||
|
|
||
| * [ ] [Compute Admin](https://cloud.google.com/compute/docs/access/iam) or | ||
| [Compute Security Admin](https://cloud.google.com/compute/docs/access/iam) on the project. | ||
|
|
||
| To let IAP Desktop connect to Cloud SQL, you need an additional VM that runs the | ||
| [Cloud SQL Auth Proxy :octicons-link-external-16:](https://cloud.google.com/sql/docs/mysql/sql-proxy). This VM is necessary | ||
| because IAP-TCP doesn't support creating tunnels to managed services such as Cloud SQL. | ||
|
|
||
|  | ||
|
|
||
|
|
||
| This guide describes how to do the following: | ||
|
|
||
| 1. Create a [container VM :octicons-link-external-16:](https://cloud.google.com/compute/docs/containers/deploying-containers) that runs | ||
| the `cloud-sql-connectors/cloud-sql-proxy` Docker image. | ||
| 1. Grant the VM permission to access Cloud SQL. | ||
| 1. Create a firewall rule that allows IAP-TCP to connect to the VM. | ||
|
|
||
| ## Deploy the Cloud SQL Proxy VM | ||
|
|
||
| To deploy a VM that [automatically runs the Cloud SQL Auth Docker image :octicons-link-external-16:](https://cloud.google.com/compute/docs/containers/deploying-containers), | ||
| do the following: | ||
|
|
||
| 1. Set your default [project ID :octicons-link-external-16:](https://cloud.google.com/resource-manager/docs/creating-managing-projects): | ||
|
|
||
| gcloud config set project PROJECT_ID | ||
|
|
||
| Replace `PROJECT_ID` with the ID of your Cloud SQL project. | ||
|
|
||
| 1. Set your default zone: | ||
|
|
||
| gcloud config set compute/zone ZONE | ||
|
|
||
| Replace `ZONE` with the ID of the zone you want to deploy the VM in. | ||
|
|
||
| 1. Create a service account for the VM: | ||
|
|
||
| SERVICE_ACCOUNT=$(gcloud iam service-accounts create cloudsql-proxy-vm --display-name "Cloud SQL Proxy VM" --format "value(email)") | ||
|
|
||
| 1. Allow the service accounr to connect to Cloud SQL by granting it the | ||
| _Cloud SQL Client_ role (`roles/cloudsql.client`): | ||
|
|
||
| gcloud projects add-iam-policy-binding $(gcloud config get project) \ | ||
| --member "serviceAccount:$SERVICE_ACCOUNT" \ | ||
| --role "roles/cloudsql.client" | ||
|
|
||
| 1. Set an environment variable that contains the | ||
| [connection name :octicons-link-external-16:](https://cloud.google.com/sql/docs/mysql/connect-auth-proxy#start-proxy) | ||
| of your Cloud SQL instance: | ||
|
|
||
| CONNECTION_NAME=$(gcloud sql instances describe --format "value(connectionName)" SQL_INSTANCE_NAME) | ||
|
|
||
| Replace `SQL_INSTANCE_NAME` with the name of your Cloud SQL instance. | ||
|
|
||
| 1. Create a [container VM :octicons-link-external-16:](https://cloud.google.com/compute/docs/containers/deploying-containers) that runs | ||
| the `cloud-sql-connectors/cloud-sql-proxy` Docker image and attach the service account: | ||
|
|
||
| gcloud compute instances create-with-container cloudsql-proxy \ | ||
| --machine-type e2-small \ | ||
| --service-account $SERVICE_ACCOUNT \ | ||
| --scopes "https://www.googleapis.com/auth/cloud-platform" \ | ||
| --no-address \ | ||
| --container-image gcr.io/cloud-sql-connectors/cloud-sql-proxy:latest \ | ||
| --container-restart-policy on-failure \ | ||
| --container-arg="--private-ip" \ | ||
| --container-arg="-a" \ | ||
| --container-arg="0.0.0.0" \ | ||
| --container-arg="$CONNECTION_NAME" \ | ||
| --network VPC_NAME \ | ||
| --subnet SUBNET | ||
|
|
||
| Replace the following: | ||
|
|
||
| + `VPC_NAME`: the name of your VPC network | ||
| + `SUBNET`: the name of the subnet to deploy the VM into. | ||
|
|
||
| The command configures the Cloud SQL Auth Proxy to listen on `0.0.0.0` (as opposed to `127.0.0.1`). | ||
| This is necessary so that IAP-TCP can connect to the Cloud SQL Auth Proxy from over the network. | ||
|
|
||
| The VM doesn't have an external IP, because it's only intended to be access from IAP-TCP. | ||
|
|
||
| 1. Create a firewall rule that allows IAP-TCP to connect to the VM: | ||
|
|
||
| gcloud compute firewall-rules create allow-sql-ingress-from-iap \ | ||
| --direction INGRESS \ | ||
| --action allow \ | ||
| --target-service-accounts $SERVICE_ACCOUNT \ | ||
| --source-ranges 35.235.240.0/20 \ | ||
| --network VPC_NAME \ | ||
| --rules tcp:PORT | ||
|
|
||
| Replace the following: | ||
|
|
||
| + `VPC_NAME`: the name of your VPC network | ||
| + `PORT`: the port of the database, for example: | ||
|
|
||
| + SQL Server: `1433` | ||
| + MySQL: `3306` | ||
| + PostgreSQL: `5432` | ||
|
|
||
| You can now use IAP Desktop to connect to `cloudsql-proxy`, and the VM forwards | ||
| connections to your Cloud SQL instance. |
Oops, something went wrong.