This page summarizes the Cloud SQL Auth Proxy and describes how to use it to establish authorized, encrypted, and secured connections to your instances.
For step-by-step instructions on using the Cloud SQL Auth Proxy, follow the link for 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 to Cloud SQL from App Engine standard environment or App Engine flexible environment.
Benefits of the Cloud SQL Auth Proxy
The Cloud SQL Auth Proxy is a Cloud SQL connector that provides secure access to your instances without a need for Authorized networks or for configuring SSL.
The Cloud SQL Auth Proxy and other Cloud SQL Connectors have the following benefits:
- Secure connections: The Cloud SQL Auth Proxy automatically encrypts traffic to and from the database using TLS 1.3 with the cipher selection determined by Go's rules. SSL certificates are used to verify client and server identities, and are independent of database protocols; you won't need to manage SSL certificates.
- Easier connection authorization: The Cloud SQL Auth Proxy uses IAM permissions to control who and what can connect to your Cloud SQL instances. Thus, the Cloud SQL Auth Proxy handles authentication with Cloud SQL, removing the need to provide static IP addresses.
- IAM database authentication. Optionally, the Cloud SQL Auth Proxy supports an automatic refresh of OAuth 2.0 access tokens. For information about this functionality, see Cloud SQL IAM database authentication.
The Cloud SQL Auth Proxy does not provide a new connectivity path; it relies on existing IP connectivity. To connect to a Cloud SQL instance using private IP, the Cloud SQL Auth Proxy must be on a resource with access to the same VPC network as the instance.
How the Cloud SQL Auth Proxy works
The Cloud SQL Auth Proxy works by having a local client running in the local environment. Your application communicates with the Cloud SQL Auth Proxy with the standard database protocol used by your database.
The Cloud SQL Auth Proxy uses a secure tunnel to communicate with its companion process running on the server. Each connection established through the Cloud SQL Auth Proxy creates one connection to the Cloud SQL instance.
When an application connects to Cloud SQL Auth Proxy, it checks whether an existing connection between it and the target Cloud SQL instance is available. If a connection does not exist, it calls Cloud SQL Admin APIs to obtain an ephemeral SSL certificate and uses it to connect to Cloud SQL. Ephemeral SSL certificates expire in approximately an hour. Cloud SQL Auth Proxy refreshes these certificates before they expire.
While the Cloud SQL Auth Proxy can listen on any port, it creates outgoing or egress
connections to your Cloud SQL instance only on port 3307. Because
Cloud SQL Auth Proxy calls APIs through the domain name sqladmin.googleapis.com
,
which does not have a fixed IP address, all egress TCP connections on port 443
must be allowed. If your client machine has an outbound firewall policy, make
sure it allows outgoing connections to port 3307 on your Cloud SQL
instance's IP.
The Cloud SQL Auth Proxy doesn't provide connection pooling, but can be paired with other connection pooling to increase efficiency.
The following diagram shows how the Cloud SQL Auth Proxy connects to Cloud SQL:
Requirements for using the Cloud SQL Auth Proxy
To use the Cloud SQL Auth Proxy, you must meet the following requirements:
- The Cloud SQL Admin API must be enabled.
- You must provide the Cloud SQL Auth Proxy with Google 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 use private 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 using
shared certificate authority (CA)
for its serverCaMode
setting,
then on the client side, you must use Cloud SQL Auth Proxy version 2.13.0 or later.
(Preview).
Download and install the Cloud SQL Auth Proxy
Linux 64-bit
- Download the Cloud SQL Auth Proxy:
curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.linux.amd64
- Make the Cloud SQL Auth Proxy executable:
chmod +x cloud-sql-proxy
Linux 32-bit
- Download the Cloud SQL Auth Proxy:
curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.linux.386
- If the
curl
command is not found, runsudo apt install curl
and repeat the download command. - Make the Cloud SQL Auth Proxy executable:
chmod +x cloud-sql-proxy
macOS 64-bit
- Download the Cloud SQL Auth Proxy:
curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.darwin.amd64
- Make the Cloud SQL Auth Proxy executable:
chmod +x cloud-sql-proxy
Mac M1
- Download the Cloud SQL Auth Proxy:
curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.darwin.arm64
- Make the Cloud SQL Auth Proxy executable:
chmod +x cloud-sql-proxy
Windows 64-bit
Right-click https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.x64.exe and select Save Link As to download the Cloud SQL Auth Proxy. Rename the file tocloud-sql-proxy.exe
.
Windows 32-bit
Right-click https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.x86.exe and select Save Link As to download the Cloud SQL Auth Proxy. Rename the file tocloud-sql-proxy.exe
.
Cloud SQL Auth Proxy Docker image
The Cloud SQL Auth Proxy has different container images, such as distroless
, alpine
,
and buster
. The default Cloud SQL Auth Proxy container image uses
distroless
, which
contains no shell. If you need a shell or related tools, then download an image based on
alpine
or buster
.
For more information, see
Cloud SQL Auth Proxy Container Images.
You can pull the latest image to your local machine using Docker by using the following command:
docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.13.0
Other OS
For other operating systems not included here, you can compile the Cloud SQL Auth Proxy from source.Cloud SQL Auth Proxy startup options
When you start the Cloud SQL Auth Proxy, you provide it with the following information:
- What Cloud SQL instances to establish connections to
- Where it will listen for data coming from your application to be sent to Cloud SQL
- Where it will find the credentials it will use to authenticate your application to Cloud SQL
- If required, which IP address type to use.
The Cloud SQL Auth Proxy startup options you provide determine whether it will listen on a TCP
port or on a Unix socket. If it is listening on a Unix socket, it creates the
socket at the location you choose; usually, the /cloudsql/ directory.
For TCP, the Cloud SQL Auth Proxy listens on localhost
by default.
Run the cloud-sql-proxy
executable with the argument --help
to
view the complete list of startup options.
You can install the Cloud SQL Auth Proxy anywhere in your local environment. The location of the Cloud SQL Auth Proxy binaries does not impact where it listens for data from your application.
For more information about how to start the Cloud SQL Auth Proxy, see Start the Cloud SQL Auth Proxy.
Use a service account for authentication
The Cloud SQL Auth Proxy requires authenticating as a Cloud SQL IAM identity to authorize your connections to a Cloud SQL instance.
The advantage of using a service account for this purpose is that you can create a credential file specifically for the Cloud SQL Auth Proxy, and it is explicitly and permanently linked to the Cloud SQL Auth Proxy as long as it is running. For this reason, using a service account is the recommended method for production instances not running on a Compute Engine instance.
The credential file can be duplicated in a system image if you need to invoke the Cloud SQL Auth Proxy from multiple machines.
To use this method, you must create and manage the credential file. Only users
with the resourcemanager.projects.setIamPolicy
permission
(such as project owners) can create the service account. If your
Google Cloud user does not have this permission, you must have someone
else create the service account for you, or use another method to
authenticate 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, you
must create it with sufficient permissions. If you are using the finer-grained
Identity Access and Management (IAM) roles to manage your
Cloud SQL permissions, you must give the service account a role that
includes the cloudsql.instances.connect
permission. The predefined
Cloud 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 service account 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 the current version is by checking the Cloud SQL Auth Proxy GitHub releases page. Future proxy releases will also be noted in the Google Groups Cloud SQL announce forum.
API usage
The Cloud SQL Auth Proxy issues requests to the Cloud SQL Admin API. These requests count against the API quota for your project.
The highest API usage occurs when you start the Cloud SQL Auth Proxy. While the Cloud 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. These options determine where and how the Cloud SQL Auth Proxy creates the sockets it uses for communicating 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 some steps you can take to ensure that the Cloud SQL Auth Proxy provides the required availability 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 are
dropped, and your application cannot create any more connections to the
Cloud SQL instance with the Cloud SQL Auth Proxy. To prevent this scenario, be sure to
run the Cloud SQL Auth Proxy as a persistent service, so that if the Cloud SQL Auth Proxy exits for any
reason, it is automatically restarted. This can be accomplished by using a
service such as systemd
, upstart
, or supervisor
. For the Windows operating
system, run the Cloud SQL Auth Proxy as a Windows Service. In general, make sure the Cloud SQL Auth Proxy has
the same uptime requirements as your application process.
How many copies of the Cloud SQL Auth Proxy your application needs
There is no need to create a proxy process for every application process; many application processes can share a single Cloud SQL Auth Proxy process. Run one Cloud SQL Auth Proxy client process per workstation or virtual machine.
If you are using auto-scaling for virtual machines, ensure that the Cloud SQL Auth Proxy is included in your virtual machine configuration, so that whenever a new virtual machine is started, it has its own Cloud SQL Auth Proxy process.
It is up to you to manage how many connections your application requires, whether by limiting or pooling the connections. The Cloud SQL Auth Proxy does not place any limitations on new connection rates or persistent connection count.
Reduce Cloud SQL Auth Proxy output
If you need to reduce the size of the Cloud SQL Auth Proxy log, you can do so by setting
--quiet
when you start the Cloud SQL Auth Proxy. Keep in mind, however, that doing
so reduces the effectiveness of the Cloud SQL Auth Proxy output in diagnosing connection
issues.
How failover affects the Cloud SQL Auth Proxy
If you are running the Cloud SQL Auth Proxy on an instance configured for High Availability, and a failover occurs, connections through the Cloud SQL Auth Proxy are affected the same way as connections over IP: all existing connections are lost, and the application must establish new connections. However, no manual intervention is required; the application can continue using the same connection strings it was before.
Keep the Cloud SQL Auth Proxy Docker image up to date
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 new version of the Cloud SQL Auth Proxy Docker image to keep your environment up to date. You can see the current version of the Cloud SQL Auth Proxy by checking the Cloud 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 using ConnectorEnforcement. With connector enforcement, direct database connection are rejected.
To use connector enforcement, you use the ConnectorEnforcement
field in the instances
API.
For more information, see Edit instances.
About the Cloud SQL Proxy Operator
Cloud SQL Proxy Operator is an open-source Kubernetes operator that automates connecting workloads in a GKE cluster to Cloud SQL databases. The Cloud SQL Auth Proxy Operator utilizes a custom resource AuthProxyWorkload that specifies the Cloud SQL Auth Proxy configuration for a specific workload. The Cloud SQL Auth Proxy Operator reads this resource and adds a Cloud SQL Auth Proxy container with the required configuration to the appropriate workloads.
When you install the operator in your GKE cluster and configure your workloads and Cloud SQL instances, the Cloud SQL Auth Proxy Operator automatically configures the Cloud 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 Proxy is unable to connect, the Cloud SQL Auth Proxy Operator outputs debugging information, and provides you with guidance to troubleshoot and repair common configuration issues.
For more information, see Connect using the Cloud SQL Proxy Operator.