This page summarizes the Cloud SQL Auth Proxy and describes how to use it to establishauthorized, encrypted, and secured connections to your instances.

For step-by-step instructions on using the Cloud SQL Auth Proxy, follow the linkfor your environment:

• Quickstart for using the Cloud SQL Auth Proxy
• How to connect using the Cloud SQL Auth Proxy
• How to connect using the Cloud SQL Auth Proxy from GKE

You do not need to use the Cloud SQL Auth Proxy or configure SSL to connect toCloud SQL fromApp Engine standard environmentorApp Engine flexible environment.

Benefits of the Cloud SQL Auth Proxy

TheCloud SQL Auth Proxy is a Cloud SQL connector that provides secure access to yourinstances withouta need forAuthorized networksor forconfiguring SSL.

The Cloud SQL Auth Proxy andother Cloud SQL Connectors have thefollowing benefits:

• Secure connections: The Cloud SQL Auth Proxy automatically encrypts traffic to andfrom the database using TLS 1.3 with the cipher selection determined byGo's rules. SSL certificates are usedto verify client and server identities, and are independent of databaseprotocols; you won't need to manage SSL certificates.
• Easier connection authorization: The Cloud SQL Auth Proxy uses IAM permissions tocontrol who and what can connect to your Cloud SQL instances. Thus, theCloud SQL Auth Proxy handles authentication with Cloud SQL, removing the need to providestatic IP addresses.
• IAM database authentication. Optionally, the Cloud SQL Auth Proxy supports anautomatic refresh of OAuth 2.0 access tokens. For information about thisfunctionality, seeCloud SQL IAM database authentication.

The Cloud SQL Auth Proxy does not provide a new connectivity path; it relies on existing IPconnectivity. To connect to a Cloud SQL instance usingprivate IP, the Cloud SQL Auth Proxy must be on a resource with accessto the same VPC network as the instance.

Limitations

You can't use the Cloud SQL Auth Proxy if you're usingcontext-aware access andIAM database authentication. When you try to login to the instance,IAM authentication fails.

How the Cloud SQL Auth Proxy works

The Cloud SQL Auth Proxy works by having a local client runningin the local environment. Your application communicates with the Cloud SQL Auth Proxywith the standard database protocol used by your database.

The Cloud SQL Auth Proxy uses a secure tunnel to communicate with its companion processrunning on the server. Each connection established through the Cloud SQL Auth Proxy createsone connection to the Cloud SQL instance.

When an application connects to Cloud SQL Auth Proxy, it checks whether an existingconnection between it and the target Cloud SQL instance is available.If a connection does not exist, it calls Cloud SQL Admin APIs to obtainan ephemeral SSL certificate and uses it to connect to Cloud SQL.Ephemeral SSL certificates expire in approximately an hour. Cloud SQL Auth Proxy refreshesthese certificates before they expire.

• Cloud SQL Connectors call APIs through thesqladmin.googleapis.com domain name. This domain name doesn't have a fixed IP address. Therefore, you must allow all egress TCP connections on port443. (Port443 is the standard HTTPS port. Whenever you go to a website or make an API request, the secure connection goes through port443 of the IP address to which the website or endpoint resolves.)
• While Cloud SQL Connectors can listen on any port, they create outgoing (or egress) connections to your Cloud SQL instance only on port3307. If your client machine has an outbound firewall policy, then make sure it allows outgoing connections to port3307 on your Cloud SQL instance's IP address. For more information, seeOptions for authenticating Cloud SQL Connectors.

For more information about these ports, seeLog in with automatic IAM database authentication.

The Cloud SQL Auth Proxy doesn't provideconnection pooling,but can be paired with other connection pooling to increase efficiency.

• The Cloud SQL Admin API must be enabled.
• You must provide the Cloud SQL Auth Proxy withGoogle Cloud authentication credentials.
• You must provide the Cloud SQL Auth Proxy with a valid database user account and password.

• The instance must either have a public IPv4 address, or be configured to useprivate IP.

  The public IP address does not need to be accessible to any external address(it does not need to be added as an authorized network address).

If the Cloud SQL instance to which you're connecting is usingshared certificate authority (CA)for itsserverCaMode setting,then on the client side, you must use Cloud SQL Auth Proxy version 2.13.0 or later.

If the Cloud SQL instance to which you're connecting is usingcustomer-managed CAfor itsserverCaMode setting,then on the client side, you must use Cloud SQL Auth Proxy version 2.14.3 or later.

When an instance uses customer-managed CA as its server CA mode, you can configurethe instance with acustom DNS name.You provide the custom DNS name in thecustom subject alternative name (SAN) field of the server certificate.

After you set up a custom DNS name for the instance, you can connect to theinstance from Cloud SQL Language Connectors using the DNS name.

Download and install the Cloud SQL Auth Proxy

docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.18.0

For more information about how to start the Cloud SQL Auth Proxy, seeStart the Cloud SQL Auth Proxy.

Use a service account for authentication

The Cloud SQL Auth Proxy requires authenticating as a Cloud SQL IAM identityto authorize your connections to a Cloud SQL instance.

The advantage of using a service account forthis purpose is that you can create a credential file specifically for theCloud SQL Auth Proxy, and it is explicitly and permanently linked to the Cloud SQL Auth Proxy as long as it isrunning. For this reason, using a service account is the recommended method for productioninstances not running on a Compute Engine instance.

The credential file can be duplicated in a system image if you need to invokethe Cloud SQL Auth Proxy from multiple machines.

To use this method, you must create and manage the credential file. Only userswith theresourcemanager.projects.setIamPolicy permission(such as project owners) can create the service account. If yourGoogle Cloud user does not have this permission, you must have someoneelse create the service account for you, or use another method toauthenticate the Cloud SQL Auth Proxy.

Learn how to Create a service account.

Required permissions for service accounts

When you use a service account to provide the credentials for the Cloud SQL Auth Proxy, youmust create it with sufficient permissions. If you are using the finer-grainedIdentity Access and Management (IAM) roles to manage yourCloud SQL permissions, you must give the service account a role thatincludes thecloudsql.instances.connect permission. The predefinedCloud SQL roles that include this permission are:

• Cloud SQL Client
• Cloud SQL Editor
• Cloud SQL Admin

If you are using the legacy project roles (Viewer, Editor, Owner), the serviceaccount must have at least the Editor role.

Keep the Cloud SQL Auth Proxy up to date

Google occasionally releases new versions of the Cloud SQL Auth Proxy. You can see what thecurrent version is by checking theCloud SQL Auth Proxy GitHub releases page.Future proxy releases will also be noted in theGoogle Groups Cloud SQL announce forum.

API usage

The Cloud SQL Auth Proxy issues requests to the Cloud SQL Admin API. These requests countagainst the API quota for your project.

The highest API usage occurs when you start the Cloud SQL Auth Proxy. While theCloud SQL Auth Proxy is running, it issues 2 API calls per hour per connected instance.

Cloud SQL Auth Proxy parameters and flags

The Cloud SQL Auth Proxy accepts several flags and parameters when it is started. Theseoptions determine where and how the Cloud SQL Auth Proxy creates the sockets it uses forcommunicating with Cloud SQL, and how it authenticates.

For help with Cloud SQL Auth Proxy options, see the following information:

• Options for authenticating the Cloud SQL Auth Proxy
• Example Cloud SQL Auth Proxy invocations
• Cloud SQL Auth Proxy GitHub page
• The Cloud SQL Auth Proxy help, displayed with./cloud-sql-proxy --help

Use the Cloud SQL Auth Proxy in a production environment

When you are using the Cloud SQL Auth Proxy in a production environment, there are somesteps you can take to ensure that the Cloud SQL Auth Proxy provides the requiredavailability for your application.

Ensure that the Cloud SQL Auth Proxy is run as a persistent service

If the Cloud SQL Auth Proxy process is stopped, all existing connections through it aredropped, and your application cannot create any more connections to theCloud SQL instance with the Cloud SQL Auth Proxy. To prevent this scenario, be sure torun the Cloud SQL Auth Proxy as a persistent service, so that if the Cloud SQL Auth Proxy exits for anyreason, it is automatically restarted. This can be accomplished by using aservice such assystemd,upstart, orsupervisor. For the Windows operatingsystem, run the Cloud SQL Auth Proxy as a Windows Service. In general, make sure the Cloud SQL Auth Proxy hasthe same uptime requirements as your application process.

The Cloud SQL Auth Proxy Docker image is based on a specific version of the Cloud SQL Auth Proxy.When a new version of the Cloud SQL Auth Proxy becomes available, pull the newversion of the Cloud SQL Auth Proxy Docker image to keep your environment up to date. Youcan see the current version of the Cloud SQL Auth Proxy by checking theCloud SQL Auth Proxy GitHub releases page.

How to enforce use of the Cloud SQL Auth Proxy

You can enforce the use of the Cloud SQL Auth Proxy in Cloud SQL instance connections usingConnectorEnforcement.With connector enforcement, direct database connection are rejected.

To use connector enforcement, you use theConnectorEnforcement field in theinstances API.

If you're using aPrivate Service Connect-enabled instance, then there's a limitation. If the instance has connector enforcement enabled, then you can't create read replicas for the instance. Similarly, if the instance has read replicas, then you can't enable connector enforcement for the instance.

For more information about how to enforce using only the Cloud SQL Auth Proxy or Cloud SQL Language Connectors to connect to an instance, seeEnforce the use of the Cloud SQL Auth Proxy.

About the Cloud SQL Proxy Operator

Cloud SQL Proxy Operator is an open-source Kubernetes operator that automatesconnecting workloads in a GKE cluster to Cloud SQL databases. TheCloud SQL Auth Proxy Operator utilizes a custom resource AuthProxyWorkload that specifiesthe Cloud SQL Auth Proxy configuration for a specific workload. The Cloud SQL Auth Proxy Operatorreads this resource and adds a Cloud SQL Auth Proxy container with the required configurationto the appropriate workloads.

When you install the operator in your GKE cluster and configure your workloadsand Cloud SQL instances, the Cloud SQL Auth Proxy Operator automatically configures theCloud SQL Auth Proxy and connects the GKE workloads to your Cloud SQL instances.

Cloud SQL Auth Proxy Operator also checks the status of the Cloud SQL Auth Proxy. If the Cloud SQL Auth Proxyis unable to connect, the Cloud SQL Auth Proxy Operator outputs debugging information,and provides you with guidance to troubleshoot and repair common configurationissues.

For more information, seeConnect using the Cloud SQL Proxy Operator.

What's next

• Learn more about the Cloud SQL Auth Proxy.