Connect to Cloud SQL from Google Kubernetes Engine (original) (raw)

This page describes how to set up a connection from an application running in Google Kubernetes Engine (GKE) to a Cloud SQL instance.

For step-by-step instructions on running a Google Kubernetes Engine sample web application connected to Cloud SQL, see thequickstart for connecting from Google Kubernetes Engine.

Cloud SQL is a fully-managed database service that helps you set up, maintain, manage, and administer your relational databases in the cloud.

Google Kubernetes Engine is a simple way to automatically deploy, scale, and manage Kubernetes.

About connecting Google Kubernetes Engine to Cloud SQL

To access a Cloud SQL instance from an application running in Google Kubernetes Engine, you can use either the Cloud SQL Auth Proxy (with public or private IP), or connect directly using a private IP address.

The Cloud SQL Auth Proxy is the recommended way to connect to Cloud SQL, even when using private IP. This is because the Cloud SQL Auth Proxy provides strong encryption and authentication using IAM, which can help keep your database secure.

Database connections consume resources on the server and the connecting application. Always use good connection management practices to minimize your application's footprint and reduce the likelihood of exceeding Cloud SQL connection limits. For more information, seeManaging database connections.

Before you begin

To connect to Cloud SQL you must have:

About Kubernetes Secrets

In Kubernetes, Secretsare a secure way to pass configuration details to your application. You can create a Secret with details such as your database name, user, and password which can be injected into your application as env vars.

There are many different ways Secrets can be used, depending on the connection type:

For complete examples of how to use Secrets, see the GitHub repositories referenced later on this page.

Create a Secret object

  1. You create the Secret objects by using the kubectl create secret command.
    To create a database credentials Secret:
kubectl create secret generic <YOUR-DB-SECRET> \  
  --from-literal=username=<YOUR-DATABASE-USER> \  
  --from-literal=password=<YOUR-DATABASE-PASSWORD> \  
  --from-literal=database=<YOUR-DATABASE-NAME>
  1. Once created, you can view the objects in the Configuration section of the Google Kubernetes Engine page in the Google Cloud console.

Connect to Cloud SQL using the Cloud SQL Auth Proxy

When you connect using the Cloud SQL Auth Proxy, the Cloud SQL Auth Proxy is added to your pod using the sidecar container pattern. The Cloud SQL Auth Proxy container is in the same pod as your application, which enables the application to connect to the Cloud SQL Auth Proxy using localhost, increasing security and performance.

For more information about the Cloud SQL Auth Proxy, see About the Cloud SQL Auth Proxy. For more information about working with pods, seePod Overview in the Kubernetes documentation.

For connecting using the Cloud SQL Auth Proxy you need the following:

  1. The instance connection name of your Cloud SQL instance.
    The instance connection name is available in the Cloud SQL Instance details page of the Google Cloud console or from thegcloud sql instances describe INSTANCE_ID command.
  2. The location of the key file associated with a service account with the proper privileges for your Cloud SQL instance.
    See Creating a service account for more information.
  3. The Cloud SQL Admin API is enabled.
    Enable the API

Provide the service account to the Cloud SQL Auth Proxy

The first step to running the Cloud SQL Auth Proxy in Google Kubernetes Engine is creating a Google Service Account (GSA) to represent your application. It is recommended that you create a service account unique to each application, instead of using the same service account everywhere. This model is more secure since it allows you to limit permissions on a per-application basis.

The service account for your application needs to meet the following criteria:

You need to configure GKE to provide the service account to the Cloud SQL Auth Proxy. There are two recommended ways to do this: workload identity or a service account key file.

Workload Identity

If you are using Google Kubernetes Engine, the preferred method is to use GKE's Workload Identity feature. This method allows you to bind a Kubernetes Service Account (KSA) to a Google Service Account (GSA). The GSA will then be accessible to applications using the matching KSA.

A Google Service Account (GSA) is an IAM identity that represents your application in Google Cloud. In a similar fashion, a Kubernetes Service Account (KSA) is a an identity that represents your application in a Google Kubernetes Engine cluster.

Workload Identity binds a KSA to a GSA, causing any deployments with that KSA to authenticate as the GSA in their interactions with Google Cloud.

  1. Enable Workload Identity for your cluster
  2. Typically, each application has its own identity, represented by a KSA and GSA pair. Create a KSA for your application by runningkubectl apply -f service-account.yaml:
  3. Enable the IAM binding between your YOUR-GSA-NAME andYOUR-KSA-NAME:
    gcloud iam service-accounts add-iam-policy-binding \
    --role="roles/iam.workloadIdentityUser" \
    --member="serviceAccount:YOUR-GOOGLE-CLOUD-PROJECT.svc.id.goog[YOUR-K8S-NAMESPACE/YOUR-KSA-NAME]" \
    YOUR-GSA-NAME@YOUR-GOOGLE-CLOUD-PROJECT.iam.gserviceaccount.com
  4. Add an annotation to YOUR-KSA-NAME to complete the binding:
    kubectl annotate serviceaccount \
    YOUR-KSA-NAME \
    iam.gke.io/gcp-service-account=YOUR-GSA-NAME@YOUR-GOOGLE-CLOUD-PROJECT.iam.gserviceaccount.com
  5. Finally, make sure to specify the service account for the k8s object.

Service account key file

Alternatively, if you can't use Workload Identity, the recommended pattern is to mount a service account key file into the Cloud SQL Auth Proxy pod and use the--credentials-file flag.

  1. Create a credential file for your service account key:
    gcloud iam service-accounts keys create ~/key.json \
    --iam-account=YOUR-SA-NAME@project-id.iam.gserviceaccount.com
  2. Turn your service account key into a k8s Secret:
    kubectl create secret generic YOUR-SA-SECRET \
    --from-file=service_account.json=~/key.json
  3. Mount the secret as a volume under the spec: for your k8s object:
  4. Follow the instructions in the next section to access the volume from the Cloud SQL Auth Proxy's pod.

Run the Cloud SQL Auth Proxy in a sidecar pattern

We recommend running the Cloud SQL Auth Proxy in a sidecar pattern (as an additional container sharing a pod with your application). We recommend this over running as a separate service for several reasons:

Complete sample configuration files:

Workload identity

Service account key

Connect to Cloud SQL without the Cloud SQL Auth Proxy

While not as secure, it is possible to connect from a VPC-native GKE cluster to a Cloud SQL instance on the same VPC using private IP without the Cloud SQL Auth Proxy.

  1. Create a secret with your instance's private IP address:
kubectl create secret generic <YOUR-PRIVATE-IP-SECRET> \  
    --from-literal=db_host=<YOUR-PRIVATE-IP-ADDRESS>
  1. Next make sure you add the secret to your application's container:
  2. Finally, configure your application to connect using the IP address from theDB_HOST env var. You will need to use the correct port for MySQL: 3306

Complete sample configuration file:

Private IP

Troubleshooting

Need help? For help troubleshooting the proxy, see Troubleshooting Cloud SQL Auth Proxy connections, or see our Cloud SQL Support page.

What's next