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

For step-by-step instructions on running a Google Kubernetes Engine sample webapplication connected to Cloud SQL, see thequickstart for connectingfrom 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, andmanage Kubernetes.

About connecting Google Kubernetes Engine to Cloud SQL

To access a Cloud SQL instance from an application running inGoogle 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 whenusing private IP. This is because the Cloud SQL Auth Proxy provides strong encryption andauthentication using IAM, which can help keep your database secure.

Database connections consume resources on the server and the connectingapplication. Always use good connection management practices to minimizeyour application's footprint and reduce the likelihood of exceedingCloud SQLconnection limits.For more information, seeManaging database connections.

Before you begin

To connect to Cloud SQL you must have:

• A GKE cluster, with thekubectl command-line tool installed and configured to communicate with thecluster.

  For help getting started with GKE, seeDeploy an app to a GKE cluster.

  For connecting using private IP, the GKEcluster must beVPC-nativeand peered with the same Virtual Private Cloud (VPC) network as the Cloud SQL instance.

• An instance created.

  For help creating a Cloud SQL instance, seeCreating Instances.

• A PostgreSQL user account configured on the instance.

  Your application will use this account to connect to the database.For help with creating a user account, seeCreating a user.

About Kubernetes Secrets

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

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

• A database credentials Secret includes the name of the database user you areconnecting as, and the user's database password.
• If connecting with the Cloud SQL Auth Proxy, a Secret can be used to hold your serviceaccount's credential file.
• If connecting with private IP, a Secret can be used to specify the privateIP address of your Cloud SQL instance.

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

Create a Secret object

1. You create the Secret objects by using thekubectl create secret command.

   To create a database credentials Secret:

   kubectlcreatesecretgeneric<YOUR-DB-SECRET>\--from-literal=username=<YOUR-DATABASE-USER>\--from-literal=password=<YOUR-DATABASE-PASSWORD>\--from-literal=database=<YOUR-DATABASE-NAME>

2. Once created, you can view the objects in theConfiguration section ofthe Google Kubernetes Engine page in theGoogle 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 Proxyis added to your pod using thesidecar container pattern. TheCloud SQL Auth Proxy container is in the same pod as your application, whichenables the application to connect to the Cloud SQL Auth Proxy usinglocalhost,increasing security and performance.

For more information about the Cloud SQL Auth Proxy, seeAbout the Cloud SQL Auth Proxy.For more information about working with pods, seePod Overview in the Kubernetesdocumentation.

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 theCloud SQLInstance details page of the Google Cloud console or from thegcloud sql instances describeINSTANCE_ID command.

2. The location of the key file associated with a service account with theproper privileges for your Cloud SQL instance.

   SeeCreating 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 aGoogle Service Account (GSA) to represent your application. It is recommended that you createa service account unique to each application, instead of using the same serviceaccount everywhere. This model is more secure since it allows you to limitpermissions on a per-application basis.

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

• Belong to a project with the Cloud SQL Admin API enabled
• Has been granted the Cloud SQL Client IAM role (or equivalent) for theproject containing the instance you want to connect to
• If connecting using private IP, you must use a VPC-native GKE cluster, in thesame VPC as your Cloud SQL instance

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

Workload Identity

If you are usingGoogle Kubernetes Engine, the preferred method is touse GKE'sWorkload Identity feature. This method allows you tobind aKubernetes Service Account (KSA) to aGoogle 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 yourapplication in Google Cloud. In a similar fashion, a Kubernetes ServiceAccount (KSA) is a an identity that represents your application in aGoogle Kubernetes Engine cluster.

Workload Identity binds a KSA to a GSA, causing any deployments with that KSA toauthenticate 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 KSAand GSA pair. Create a KSA for your application by runningkubectl apply -f service-account.yaml:

   apiVersion:v1kind:ServiceAccountmetadata:name:<YOUR-KSA-NAME># TODO(developer): replace these values

3. Enable the IAM binding between yourYOUR-GSA-NAME andYOUR-KSA-NAME:

   gcloudiamservice-accountsadd-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 toYOUR-KSA-NAME to complete the binding:

   kubectlannotateserviceaccount\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.

   apiVersion:apps/v1kind:Deploymentmetadata:name:<YOUR-DEPLOYMENT-NAME>spec:selector:matchLabels:app:<YOUR-APPLICATION-NAME>template:metadata:labels:app:<YOUR-APPLICATION-NAME>spec:serviceAccountName:<YOUR-KSA-NAME>

Service account key file

Alternatively, if you can't use Workload Identity, the recommended pattern isto 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:

   gcloudiamservice-accountskeyscreate~/key.json\--iam-account=YOUR-SA-NAME@project-id.iam.gserviceaccount.com

2. Turn your service account key into a k8sSecret:

   kubectlcreatesecretgenericYOUR-SA-SECRET\--from-file=service_account.json=~/key.json

3. Mount the secret as a volume under thespec: for your k8s object:

   volumes:-name:<YOUR-SA-SECRET-VOLUME>secret:secretName:<YOUR-SA-SECRET>

4. Follow the instructions in the next section to access the volume from theCloud SQL Auth Proxy's pod.

Run the Cloud SQL Auth Proxy in a sidecar pattern

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

• Prevents your SQL traffic from being exposed locally; the Cloud SQL Auth Proxy providesencryption on outgoing connections, but you need to limit exposure forincoming connections.
• Prevents a single point of failure; each application's access toyour database is independent from the others, making it more resilient.
• Limits access to the Cloud SQL Auth Proxy, allowing you to use IAM permissions perapplication rather than exposing the database to the entire cluster.

• Allows you to scope resource requests more accurately; because theCloud SQL Auth Proxy consumes resources linearly to usage, this pattern allows you to moreaccurately scope and request resources to match your applications as itscales.

• Add the Cloud SQL Auth Proxy to the pod configuration underinitContainers:

  initContainers:-name:cloud-sql-proxyrestartPolicy:Always# It is recommended to use the latest version of the Cloud SQL Auth Proxy# Make sure to update on a regular schedule!image:gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.14.1args:# If connecting from a VPC-native GKE cluster, you can use the# following flag to have the proxy connect over private IP# - "--private-ip"# If you are not connecting with Automatic IAM, you can delete# the following flag.-"--auto-iam-authn"# Enable structured logging with LogEntry format:-"--structured-logs"# Replace DB_PORT with the port the proxy should listen on-"--port=<DB_PORT>"-"<INSTANCE_CONNECTION_NAME>"securityContext:# The default Cloud SQL Auth Proxy image runs as the# "nonroot" user and group (uid: 65532) by default.runAsNonRoot:true# You should use resource requests/limits as a best practice to prevent# pods from consuming too many resources and affecting the execution of# other pods. You should adjust the following values based on what your# application needs. For details, see# https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/resources:requests:# The proxy's memory use scales linearly with the number of active# connections. Fewer open connections will use less memory. Adjust# this value based on your application's requirements.memory:"2Gi"# The proxy's CPU use scales linearly with the amount of IO between# the database and the application. Adjust this value based on your# application's requirements.cpu:"1"

  If you're using a service account key, specify your secret volume and addthe--credentials-file flag to the command:

  # This flag specifies where the service account key can be found-"--credentials-file=/secrets/service_account.json"securityContext:# The default Cloud SQL Auth Proxy image runs as the# "nonroot" user and group (uid: 65532) by default.runAsNonRoot:truevolumeMounts:-name:<YOUR-SA-SECRET-VOLUME>mountPath:/secrets/readOnly:true

• If you're usingIAM database authentication,thenadd IAMpolicy bindings to the service account. Grantthe Cloud SQL Instance User (role/cloudsql.instanceUser) andthe Cloud SQL Client (role/cloudsql.client) roles to the service account usedby the Cloud SQL Auth Proxy.

• To log in to the instance with IAM database authentication automatically, start the Cloud SQL Auth Proxy withthe--auto-iam-authn flag.

• Finally, configure your application to connect using127.0.0.1 onwhicheverDB_PORT you specified in the command section.

Complete sample configuration files:

# Copyright 2021 Google LLC## Licensed under the Apache License, Version 2.0 (the "License");# you may not use this file except in compliance with the License.# You may obtain a copy of the License at##      http://www.apache.org/licenses/LICENSE-2.0## Unless required by applicable law or agreed to in writing, software# distributed under the License is distributed on an "AS IS" BASIS,# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.# See the License for the specific language governing permissions and# limitations under the License.apiVersion:apps/v1kind:Deploymentmetadata:name:<YOUR-DEPLOYMENT-NAME>spec:selector:matchLabels:app:<YOUR-APPLICATION-NAME>template:metadata:labels:app:<YOUR-APPLICATION-NAME>spec:serviceAccountName:<YOUR-KSA-NAME>containers:-name:<YOUR-APPLICATION-NAME># ... other container configurationenv:-name:DB_USERvalueFrom:secretKeyRef:name:<YOUR-DB-SECRET>key:username-name:DB_PASSvalueFrom:secretKeyRef:name:<YOUR-DB-SECRET>key:password-name:DB_NAMEvalueFrom:secretKeyRef:name:<YOUR-DB-SECRET>key:databaseinitContainers:-name:cloud-sql-proxyrestartPolicy:Always# It is recommended to use the latest version of the Cloud SQL Auth Proxy# Make sure to update on a regular schedule!image:gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.14.1args:# If connecting from a VPC-native GKE cluster, you can use the# following flag to have the proxy connect over private IP# - "--private-ip"# If you are not connecting with Automatic IAM, you can delete# the following flag.-"--auto-iam-authn"# Enable structured logging with LogEntry format:-"--structured-logs"# Replace DB_PORT with the port the proxy should listen on-"--port=<DB_PORT>"-"<INSTANCE_CONNECTION_NAME>"securityContext:# The default Cloud SQL Auth Proxy image runs as the# "nonroot" user and group (uid: 65532) by default.runAsNonRoot:true# You should use resource requests/limits as a best practice to prevent# pods from consuming too many resources and affecting the execution of# other pods. You should adjust the following values based on what your# application needs. For details, see# https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/resources:requests:# The proxy's memory use scales linearly with the number of active# connections. Fewer open connections will use less memory. Adjust# this value based on your application's requirements.memory:"2Gi"# The proxy's CPU use scales linearly with the amount of IO between# the database and the application. Adjust this value based on your# application's requirements.cpu:"1"

# Copyright 2021 Google LLC## Licensed under the Apache License, Version 2.0 (the "License");# you may not use this file except in compliance with the License.# You may obtain a copy of the License at##      http://www.apache.org/licenses/LICENSE-2.0## Unless required by applicable law or agreed to in writing, software# distributed under the License is distributed on an "AS IS" BASIS,# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.# See the License for the specific language governing permissions and# limitations under the License.apiVersion:apps/v1kind:Deploymentmetadata:name:<YOUR-DEPLOYMENT-NAME>spec:selector:matchLabels:app:<YOUR-APPLICATION-NAME>template:metadata:labels:app:<YOUR-APPLICATION-NAME>spec:containers:-name:<YOUR-APPLICATION-NAME># ... other container configurationenv:-name:DB_USERvalueFrom:secretKeyRef:name:<YOUR-DB-SECRET>key:username-name:DB_PASSvalueFrom:secretKeyRef:name:<YOUR-DB-SECRET>key:password-name:DB_NAMEvalueFrom:secretKeyRef:name:<YOUR-DB-SECRET>key:databaseinitContainers:-name:cloud-sql-proxyrestartPolicy:Always# It is recommended to use the latest version of the Cloud SQL Auth Proxy# Make sure to update on a regular schedule!image:gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.14.1args:# If connecting from a VPC-native GKE cluster, you can use the# following flag to have the proxy connect over private IP# - "--private-ip"# If you are not connecting with Automatic IAM AuthN, you can delete# the following flag.-"--auto-iam-authn"# Enable structured logging with LogEntry format:-"--structured-logs"# Replace DB_PORT with the port the proxy should listen on-"--port=<DB_PORT>"-"<INSTANCE_CONNECTION_NAME>"# This flag specifies where the service account key can be found-"--credentials-file=/secrets/service_account.json"securityContext:# The default Cloud SQL Auth Proxy image runs as the# "nonroot" user and group (uid: 65532) by default.runAsNonRoot:truevolumeMounts:-name:<YOUR-SA-SECRET-VOLUME>mountPath:/secrets/readOnly:true# Resource configuration depends on an application's requirements. You# should adjust the following values based on what your application# needs. For details, see https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/resources:requests:# The proxy's memory use scales linearly with the number of active# connections. Fewer open connections will use less memory. Adjust# this value based on your application's requirements.memory:"2Gi"# The proxy's CPU use scales linearly with the amount of IO between# the database and the application. Adjust this value based on your# application's requirements.cpu:"1"volumes:-name:<YOUR-SA-SECRET-VOLUME>secret:secretName:<YOUR-SA-SECRET>

Connect to Cloud SQL without the Cloud SQL Auth Proxy

While not as secure, it is possible to connect from aVPC-native GKE cluster toa 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:

   kubectlcreatesecretgeneric<YOUR-PRIVATE-IP-SECRET>\--from-literal=db_host=<YOUR-PRIVATE-IP-ADDRESS>

2. Next make sure you add the secret to your application's container:

   -name:DB_HOSTvalueFrom:secretKeyRef:name:<YOUR-PRIVATE-IP-SECRET>key:db_host

3. Finally, configure your application to connect using the IP address from theDB_HOST env var. You will need to use the correct port forPostgreSQL: 5432

Complete sample configuration file:

# Copyright 2021 Google LLC## Licensed under the Apache License, Version 2.0 (the "License");# you may not use this file except in compliance with the License.# You may obtain a copy of the License at##      http://www.apache.org/licenses/LICENSE-2.0## Unless required by applicable law or agreed to in writing, software# distributed under the License is distributed on an "AS IS" BASIS,# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.# See the License for the specific language governing permissions and# limitations under the License.apiVersion:apps/v1kind:Deploymentmetadata:name:<YOUR-DEPLOYMENT-NAME>spec:selector:matchLabels:app:<YOUR-APPLICATION-NAME>template:metadata:labels:app:<YOUR-APPLICATION-NAME>spec:containers:-name:<YOUR-APPLICATION-NAME># ... other container configurationenv:-name:DB_USERvalueFrom:secretKeyRef:name:<YOUR-DB-SECRET>key:username-name:DB_PASSvalueFrom:secretKeyRef:name:<YOUR-DB-SECRET>key:password-name:DB_NAMEvalueFrom:secretKeyRef:name:<YOUR-DB-SECRET>key:database-name:DB_HOSTvalueFrom:secretKeyRef:name:<YOUR-PRIVATE-IP-SECRET>key:db_host

Troubleshooting

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

What's next

• Learn more aboutprivate IP.

• Learn more about theCloud SQL Auth Proxy and theproxy docker image.

• Get helptroubleshooting Cloud SQL Auth Proxy connections.

• Learn more aboutGoogle Kubernetes Engine.

• Learn aboutoptions for support.