Connecting from Google Kubernetes Engine

This page describes how to set up a connection from an application running in Kubernetes Engine to a Cloud SQL instance, using the Cloud SQL Proxy Docker image.


To access a Google Cloud SQL instance from an application running in Kubernetes Engine, you use the Cloud SQL Proxy Docker image. For more information about the Cloud SQL Proxy, see About the Cloud SQL Proxy.

Before you begin

Before you start this procedure, you must have:

  • A Kubernetes Engine cluster running version 1.2 or higher, with the kubectl command-line tool installed and configured to communicate with the cluster.

    For help getting started with Kubernetes Engine, see the Quickstart.

  • An application container in a pod on the Kubernetes Engine cluster.

    The Cloud SQL Proxy is added to your pod using the "sidecar" pod pattern.

  • A Cloud SQL instance created.

    For help creating a Cloud SQL instance, see Creating Instances.

1. Enable the API

  • Enable the Cloud SQL Administration API.

    Enable the 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 Google Cloud Platform Auth Guide.

    1. Go to the Cloud SQL Service accounts page of the Google Cloud Platform Console.

      Go to the Service accounts page

    2. If needed, select the project that contains your Cloud SQL instance.
    3. Click Create service account.
    4. In the Create service account dialog, provide a descriptive name for the service account.
    5. For Role, select Cloud SQL > Cloud SQL Client.

      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.setIamPolicy permission. You can check your permissions by going to the IAM page in the Google Cloud Platform Console and searching for your user id.

    6. Change the Service account ID to a unique value that you will recognize so you can easily find this service account later if needed.
    7. Click Furnish a new private key.
    8. The default key type is JSON, which is the correct value to use.
    9. Click Create.

      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 as PROXY_KEY_FILE_PATH.

    3. Create the proxy user

    Use the gcloud command below to create the user account named proxyuser, that the proxy will use to access your Cloud SQL instance, filling in the instance name and the password.

    gcloud sql users create proxyuser host --instance=[INSTANCE_NAME] --password=[PASSWORD]

    The host value is not used and can be any non-empty string.

    For help with creating a user account, see Creating a user.

    4. Get your instance connection name

    The instance connection name identifies your 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 myproject1, the gcloud output would be:

    connectionName: myproject1:us-central1:myinstance1

    You will provide this value later as INSTANCE_CONNECTION_NAME.

    5. Create your Secrets

    You need two Secrets to enable your Kubernetes Engine application to access the data in your Cloud SQL instance:

    • The cloudsql-instance-credentials Secret contains the service account.
    • The cloudsql-db-credentials Secret provides the proxy user account and password.

    To create these Secrets:

    1. Create the Secret containing the Service Account which enables authentication to Cloud SQL:

      kubectl create secret generic cloudsql-instance-credentials \
    2. Create the Secret needed for database access, using the name and password for the proxy user you created earlier:

      kubectl create secret generic cloudsql-db-credentials \
           --from-literal=username=proxyuser --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.

    1. Provide as 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 to connect to it.

    2. Provide the cloudsql-db-credentials Secret to enable the application to log in to the database.

      For example, the following configuration provides the DB_USER and DB_PASSWORD environment variables to your application using the cloudsql- db-credentials Secret.

      - name: DB_USER
            name: cloudsql-db-credentials
            key: username
      - name: DB_PASSWORD
            name: cloudsql-db-credentials
            key: password

    3. 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
        command: ["/cloud_sql_proxy",
          - name: cloudsql-instance-credentials
            mountPath: /secrets/cloudsql
            readOnly: true
      This step also defines the mount points for your container.

    4. Define your volumes:

        - name: cloudsql-instance-credentials
            secretName: cloudsql-instance-credentials

    5. 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 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.

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

    What's next

    Send feedback about...

    Cloud SQL for PostgreSQL