This page describes how to set up a connection from an application running in Google Kubernetes Engine to a Cloud SQL instance, using the Cloud SQL Proxy Docker image.
To access a Cloud SQL instance from an application running in
Google Kubernetes Engine, you use the Cloud SQL Proxy Docker image. The Cloud SQL Proxy
is added to your pod using the "sidecar" container pattern—the
proxy container is in the same pod as your application, which
enables the application to connect to the proxy using
increasing security and performance. Learn more.
Before you begin
Before you start this procedure, you must have:
A GKE cluster running version 1.2 or higher, with the
kubectlcommand-line tool installed and configured to communicate with the cluster.
For help getting started with GKE, see the Quickstart.
An application container in a pod on the GKE cluster.
A PostgreSQL instance created.
For help creating a Cloud SQL instance, see Creating Instances.
1. Enable the APIEnable the Cloud SQL Admin API.
2. Create a service account
The proxy requires a service account with the proper privileges for your Cloud SQL instance. For more information about service accounts, see the GCP Auth Guide.
- Go to the Cloud SQL Service accounts page of the Google Cloud Platform Console.
- If needed, select the project that contains your Cloud SQL instance.
- Click Create service account.
- In the Create service account dialog, provide a descriptive name for the service account.
For Role, select one of the following roles:
- Cloud SQL > Cloud SQL Client
- Cloud SQL > Cloud SQL Editor
- Cloud SQL > Cloud SQL Admin
Alternatively, you can use the primitive Editor role by selecting Project > Editor, but the Editor role includes permissions across Google Cloud Platform.
If you do not see these roles, your Google Cloud Platform user might not have the
resourcemanager.projects.setIamPolicypermission. You can check your permissions by going to the IAM page in the Google Cloud Platform Console and searching for your user id.
- Change the Service account ID to a unique value that you will recognize so you can easily find this service account later if needed.
- Click Furnish a new private key.
The default key type is
JSON, which is the correct value to use.
The private key file is downloaded to your machine. You can move it to another location. Keep the key file secure.
You will provide the location of this key file later in this
task, when you create your secrets, as
3. Create your database user
If needed, create a PostgreSQL user that your application will use to access your database:
gcloud sql users create [DBUSER] --instance=[INSTANCE_NAME] --password=[PASSWORD]
For help with creating a user account, see Creating a user.
4. Get your instance connection name
The instance connection name identifies your Cloud SQL instance on
Google Cloud Platform. You can get it from the Google Cloud Platform Console, or by using the
gcloud command-line tool:
gcloud sql instances describe [INSTANCE_NAME]
For example, for the instance
myinstance1 in project
gcloud output would be:
You will provide this value later as
5. Create your Secrets
You need two Secrets to enable your GKE application to access the data in your Cloud SQL instance:
cloudsql-instance-credentialsSecret contains the service account.
cloudsql-db-credentialsSecret provides the database` user account and password.
To create these Secrets:
cloudsql-instance-credentialsSecret, using the key file you downloaded previously:
kubectl create secret generic cloudsql-instance-credentials \ --from-file=credentials.json=[PROXY_KEY_FILE_PATH]
cloudsql-db-credentialsSecret, using the name and password for the database user you created previously:
kubectl create secret generic cloudsql-db-credentials \ --from-literal=username=[DBUSER] --from-literal=password=[PASSWORD]
6. Update your pod configuration file
Your pod configuration file needs to include the host address of the database, the Secrets, and the location of your Cloud SQL instance.
The exact variable names needed depend on the application container you are using. For a complete sample deployment, including sample code, see sample Kubernetes Deployment manifest file on GitHub.
127.0.0.1:5432as the host address your application uses to access the database.
Because the proxy runs in a second container in the same pod, it appears to your application as
localhost, so you use
127.0.0.1:5432to connect to it.
cloudsql-db-credentialsSecret to enable the application to log in to the database.
For example, the following configuration provides the
DB_PASSWORDenvironment variables to your application using the
env: - name: DB_USER valueFrom: secretKeyRef: name: cloudsql-db-credentials key: username - name: DB_PASSWORD valueFrom: secretKeyRef: name: cloudsql-db-credentials key: password
In your Kubernetes Deployment file, define an additional container in the Pod definition to run the proxy container. This container exposes port 5432 and uses the instance connection name you recorded earlier.
- name: cloudsql-proxy image: gcr.io/cloudsql-docker/gce-proxy:1.11 command: ["/cloud_sql_proxy", "-instances=<INSTANCE_CONNECTION_NAME>=tcp:5432", "-credential_file=/secrets/cloudsql/credentials.json"] securityContext: runAsUser: 2 # non-root user allowPrivilegeEscalation: false volumeMounts: - name: cloudsql-instance-credentials mountPath: /secrets/cloudsql readOnly: true
Define your volumes:
volumes: - name: cloudsql-instance-credentials secret: secretName: cloudsql-instance-credentials
Add a securityContext to your deployment file. This causes the Cloud SQL Proxy to run as a non-root user. You can provide any user id; using a different user than other sensitive workloads is a good practice.
securityContext: runAsUser: 2 # non-root user allowPrivilegeEscalation: false
Bring up your Deployment using the Kubernetes manifest file:
kubectl apply -f deployment.yaml
7. Update your application to connect to Cloud SQL
When you have your Google Kubernetes Engine environment set up, you connect to Cloud SQL the same way as any other external application that is using the proxy. The exact connection string you use depends on what language and framework you are using.
For some example connection strings, see Language-specific information and examples.