|
| 1 | +# Connecting Cloud Run to Cloud SQL with the Go Connector |
| 2 | + |
| 3 | +This guide provides a comprehensive walkthrough of how to connect a Cloud Run service to a Cloud SQL instance using the Cloud SQL Go Connector. It covers connecting to instances with both public and private IP addresses and demonstrates how to handle database credentials securely. |
| 4 | + |
| 5 | +## Develop a Go Application |
| 6 | + |
| 7 | +The following Go applications demonstrate how to connect to a Cloud SQL instance using the Cloud SQL Go Connector. |
| 8 | + |
| 9 | +### `mysql/main.go` and `postgres/main.go` |
| 10 | + |
| 11 | +These files contain the core application logic for connecting to a Cloud SQL for MySQL or PostgreSQL instance. They provide two separate authentication methods, each exposed at a different route: |
| 12 | +- `/`: Password-based authentication |
| 13 | +- `/iam`: IAM-based authentication |
| 14 | + |
| 15 | +### `sqlserver/main.go` |
| 16 | + |
| 17 | +This file contains the core application logic for connecting to a Cloud SQL for SQL Server instance. It uses the `cloud-sql-go-connector` to create a database connection pool with password-based authentication at the `/` route. |
| 18 | + |
| 19 | +> [!NOTE] |
| 20 | +> |
| 21 | +> Cloud SQL for SQL Server does not support IAM database authentication. |
| 22 | +
|
| 23 | +> [!NOTE] |
| 24 | +> **Lazy Refresh** |
| 25 | +> |
| 26 | +> The sample code in all three `main.go` files initializes the `Dialer` with `WithLazyRefresh()` option. This is a recommended approach to avoid connection errors and optimize cost by preventing background processes from running when the CPU is throttled. |
| 27 | +
|
| 28 | + |
| 29 | +## Lazy Instantiation |
| 30 | + |
| 31 | +In a Cloud Run service, global variables are initialized when the container instance starts up. The application instance then handles subsequent requests until the container is stopped. |
| 32 | + |
| 33 | +The `Connector` (Dialer) and `sql.DB` objects are defined as global variables (initially set to `nil`) and are lazily instantiated (created only when needed) inside the request handlers using `sync.Once`. |
| 34 | + |
| 35 | +This approach offers several benefits: |
| 36 | + |
| 37 | +1. **Faster Startup:** By deferring initialization until the first request, the Cloud Run service can start listening for requests almost immediately, reducing cold start latency. |
| 38 | +2. **Resource Efficiency:** Expensive operations, like establishing background connections or fetching secrets, are only performed when actually required. |
| 39 | +3. **Connection Reuse:** Once initialized, the global `Connector` and `sql.DB` instances are reused for all subsequent requests to that container instance. This prevents the overhead of creating new connections for every request and avoids hitting connection limits. |
| 40 | + |
| 41 | +## IAM Authentication Prerequisites |
| 42 | + |
| 43 | +For IAM authentication to work, you must ensure two things: |
| 44 | + |
| 45 | +1. **The Cloud Run service's service account has the `Cloud SQL Client` role.** You can grant this role with the following command: |
| 46 | + ```bash |
| 47 | + gcloud projects add-iam-policy-binding PROJECT_ID \ |
| 48 | + --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \ |
| 49 | + --role="roles/cloudsql.client" |
| 50 | + ``` |
| 51 | + Replace `PROJECT_ID` with your Google Cloud project ID and `SERVICE_ACCOUNT_EMAIL` with the email of the service account your Cloud Run service is using. |
| 52 | + |
| 53 | +2. **The service account is added as a database user to your Cloud SQL instance.** You can do this with the following command: |
| 54 | + ```bash |
| 55 | + gcloud sql users create SERVICE_ACCOUNT_EMAIL \ |
| 56 | + --instance=INSTANCE_NAME \ |
| 57 | + --type=cloud_iam_user |
| 58 | + ``` |
| 59 | + Replace `SERVICE_ACCOUNT_EMAIL` with the same service account email and `INSTANCE_NAME` with your Cloud SQL instance name. |
| 60 | + |
| 61 | +## Deploy the Application to Cloud Run |
| 62 | + |
| 63 | +Follow these steps to deploy the application to Cloud Run. |
| 64 | + |
| 65 | +### Build and Push the Docker Image |
| 66 | + |
| 67 | +1. **Enable the Artifact Registry API:** |
| 68 | + |
| 69 | + ```bash |
| 70 | + gcloud services enable artifactregistry.googleapis.com |
| 71 | + ``` |
| 72 | + |
| 73 | +2. **Create an Artifact Registry repository:** |
| 74 | + |
| 75 | + ```bash |
| 76 | + gcloud artifacts repositories create REPO_NAME \ |
| 77 | + --repository-format=docker \ |
| 78 | + --location=REGION |
| 79 | + ``` |
| 80 | + |
| 81 | +3. **Configure Docker to authenticate with Artifact Registry:** |
| 82 | + |
| 83 | + ```bash |
| 84 | + gcloud auth configure-docker REGION-docker.pkg.dev |
| 85 | + ``` |
| 86 | + |
| 87 | +4. **Build the Docker image (replace `mysql` with `postgres` or `sqlserver` as needed):** |
| 88 | + |
| 89 | + ```bash |
| 90 | + docker build -t REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME/IMAGE_NAME mysql |
| 91 | + ``` |
| 92 | + |
| 93 | +5. **Push the Docker image to Artifact Registry:** |
| 94 | + |
| 95 | + ```bash |
| 96 | + docker push REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME/IMAGE_NAME |
| 97 | + ``` |
| 98 | + |
| 99 | +### Deploy to Cloud Run |
| 100 | + |
| 101 | +Deploy the container image to Cloud Run using the `gcloud run deploy` command. |
| 102 | + |
| 103 | +**Sample Values:** |
| 104 | +* `SERVICE_NAME`: `my-cloud-run-service` |
| 105 | +* `REGION`: `us-central1` |
| 106 | +* `PROJECT_ID`: `my-gcp-project-id` |
| 107 | +* `REPO_NAME`: `my-artifact-repo` |
| 108 | +* `IMAGE_NAME`: `my-app-image` |
| 109 | +* `INSTANCE_CONNECTION_NAME`: `my-gcp-project-id:us-central1:my-instance-name` |
| 110 | +* `DB_USER`: `my-db-user` (for password-based authentication) |
| 111 | +* `DB_IAM_USER`: `my-service-account@my-gcp-project-id.iam.gserviceaccount.com` (for IAM-based authentication) |
| 112 | +* `DB_NAME`: `my-db-name` |
| 113 | +* `DB_PASSWORD`: `my-user-pass-name` |
| 114 | +* `VPC_NETWORK`: `my-vpc-network` |
| 115 | +* `SUBNET_NAME`: `my-vpc-subnet` |
| 116 | + |
| 117 | +**For MySQL and PostgreSQL (Public IP):** |
| 118 | + |
| 119 | +```bash |
| 120 | +gcloud run deploy SERVICE_NAME \ |
| 121 | + --image=REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME/IMAGE_NAME \ |
| 122 | + --set-env-vars=DB_USER=DB_USER,DB_IAM_USER=DB_IAM_USER,DB_NAME=DB_NAME,DB_SECRET_NAME=DB_SECRET_NAME,INSTANCE_CONNECTION_NAME=INSTANCE_CONNECTION_NAME \ |
| 123 | + --region=REGION \ |
| 124 | + --update-secrets=DB_PASSWORD=DB_PASSWORD:latest |
| 125 | +``` |
| 126 | + |
| 127 | +**For MySQL and PostgreSQL (Private IP):** |
| 128 | + |
| 129 | +```bash |
| 130 | +gcloud run deploy SERVICE_NAME \ |
| 131 | + --image=REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME/IMAGE_NAME \ |
| 132 | + --set-env-vars=DB_USER=DB_USER,DB_IAM_USER=DB_IAM_USER,DB_NAME=DB_NAME,DB_SECRET_NAME=DB_SECRET_NAME,INSTANCE_CONNECTION_NAME=INSTANCE_CONNECTION_NAME,IP_TYPE=PRIVATE \ |
| 133 | + --network=VPC_NETWORK \ |
| 134 | + --subnet=SUBNET_NAME \ |
| 135 | + --vpc-egress=private-ranges-only \ |
| 136 | + --region=REGION \ |
| 137 | + --update-secrets=DB_PASSWORD=DB_PASSWORD:latest |
| 138 | +``` |
| 139 | + |
| 140 | +**For SQL Server (Public IP):** |
| 141 | + |
| 142 | +```bash |
| 143 | +gcloud run deploy SERVICE_NAME \ |
| 144 | + --image=REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME/IMAGE_NAME \ |
| 145 | + --set-env-vars=DB_USER=DB_USER,DB_NAME=DB_NAME,DB_SECRET_NAME=DB_SECRET_NAME,INSTANCE_CONNECTION_NAME=INSTANCE_CONNECTION_NAME \ |
| 146 | + --region=REGION \ |
| 147 | + --update-secrets=DB_PASSWORD=DB_PASSWORD:latest |
| 148 | +``` |
| 149 | + |
| 150 | +**For SQL Server (Private IP):** |
| 151 | + |
| 152 | +```bash |
| 153 | +gcloud run deploy SERVICE_NAME \ |
| 154 | + --image=REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME/IMAGE_name \ |
| 155 | + --set-env-vars=DB_USER=DB_USER,DB_NAME=DB_NAME,DB_SECRET_NAME=DB_SECRET_NAME,INSTANCE_CONNECTION_NAME=INSTANCE_CONNECTION_NAME,IP_TYPE=PRIVATE \ |
| 156 | + --network=VPC_NETWORK \ |
| 157 | + --subnet=SUBNET_NAME \ |
| 158 | + --vpc-egress=private-ranges-only \ |
| 159 | + --region=REGION \ |
| 160 | + --update-secrets=DB_PASSWORD=DB_PASSWORD:latest |
| 161 | +``` |
| 162 | + |
| 163 | +> [!NOTE] |
| 164 | +> **`For PSC connections`** |
| 165 | +> |
| 166 | +> To connect to the Cloud SQL instance with PSC connection type, create a PSC endpoint, a DNS zone and DNS record for the instance in the same VPC network as the Cloud Run service and replace the `IP_TYPE` in the deploy command with `PSC`. To configure DNS records, refer to [Connect to an instance using Private Service Connect](https://docs.cloud.google.com/sql/docs/mysql/configure-private-service-connect) guide |
0 commit comments