cloudsql-proxy

README

Cloud SQL Auth proxy

The Cloud SQL Auth proxy is a binary that provides IAM-based authorization and encryption when connecting to a Cloud SQL instance.

See the Connecting Overview page for more information on connecting to a Cloud SQL instance, or the About the proxy page for details on how the Cloud SQL proxy works.

Note: The Proxy cannot provide a network path to a Cloud SQL instance if one is not already present (e.g., the proxy cannot access a VPC if it does not already have access to it).

Installation

For 64-bit Linux, run:

VERSION=v1.21.0 # see Releases for other versions
wget "https://storage.googleapis.com/cloudsql-proxy/$VERSION/cloud_sql_proxy.linux.amd64" -O cloud_sql_proxy
chmod +x cloud_sql_proxy

Releases for additional OS's and architectures and be found on the releases page.

For alternative distributions, see below under third party.

Container Images

There are containerized versions of the proxy available from the following Google Cloud Container Registry repositories:

• gcr.io/cloudsql-docker/gce-proxy
• us.gcr.io/cloudsql-docker/gce-proxy
• eu.gcr.io/cloudsql-docker/gce-proxy
• asia.gcr.io/cloudsql-docker/gce-proxy

Each image is tagged with the associated proxy version. The following tags are currently supported:

• $VERSION - default image (recommended)
• $VERSION-alpine - uses alpine:3 as a base image (only supported from v1.17 up)
• $VERSION-bullseye - uses debian:bullseye as a base image (only supported from v1.17 up)
• $VERSION-bookworm - uses debian:bookworm as a base image (only supported from v1.36 up)

We recommend using the latest version of the proxy and updating the version regularly. However, we also recommend pinning to a specific tag and avoid the latest tag. Note: the tagged version is only that of the proxy. Changes in base images may break specific setups, even on non-major version increments. As such, it's a best practice to test changes before deployment, and use automated rollbacks to revert potential failures.

NOTE: As of v1.16, the default container image uses distroless. If you require a shell or similar tools, use the Alpine or Debian based (bullseye and bookworm) images listed above.

Install from Source

To install from source, ensure you have the latest version of Go installed.

Then, simply run:

go install github.com/GoogleCloudPlatform/cloudsql-proxy/cmd/cloud_sql_proxy@latest

The cloud_sql_proxy will be placed in $GOPATH/bin or $HOME/go/bin.

Usage

All the following invocations assume valid credentials are present in the environment. The following examples all reference an INSTANCE_CONNECTION_NAME, which takes the form: myproject:myregion:myinstance. To find the INSTANCE_CONNECTION_NAME, run gcloud sql instances describe <INSTANCE_NAME> where INSTANCE_NAME is the name of the database instance.

TCP socket example

# Starts the proxy listening on 127.0.0.1:5432
cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:5432

# Starts the proxy listening on port 5432 on *all* interfaces
cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:0.0.0.0:5432

Unix socket example

# The proxy will mount a Unix domain socket at /cloudsql/<INSTANCE_CONNECTION_NAME>
# Note: The directory specified by `-dir` must exist and the socket file path
# (i.e., dir plus INSTANCE_CONNECTION_NAME) must be under your platform's
# limit (typically 108 characters on many Unix systems, but varies by platform).
cloud_sql_proxy -dir=/cloudsql -instances=<INSTANCE_CONNECTION_NAME>

Private IP example

cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:5432 -ip_address_types=PRIVATE

In order to connect using Private IP, you must have access through your project's VPC. For more details, see Private IP Requirements.

Credentials

The Cloud SQL proxy uses a Cloud IAM account to authorize connections against a Cloud SQL instance. The proxy sources the credentials for these accounts in the following order:

1. The -credential_file flag
2. The -token flag
3. The service account key at the path stored in the GOOGLE_APPLICATION_CREDENTIALS environment variable.
4. The gcloud user credentials (set from gcloud auth login)
5. The Application Default Credentials

Note: Any account connecting to a Cloud SQL database will need one of the following IAM roles:

• Cloud SQL Client (preferred)
• Cloud SQL Editor
• Cloud SQL Admin

Or one may manually assign the following IAM permissions:

• cloudsql.instances.connect
• cloudsql.instances.get

See Roles and Permissions in Cloud SQL for details.

When the proxy authenticates under the Compute Engine VM's default service account, the VM must have at least the sqlservice.admin API scope (i.e., "https://www.googleapis.com/auth/sqlservice.admin") and the associated project must have the SQL Admin API enabled. The default service account must also have at least writer or editor privileges to any projects of target SQL instances.

CLI Flags

The Cloud SQL Auth proxy takes a few arguments to configure what instances to connect to and connection behavior. For a full list of flags supported by the proxy, use cloud_sql_proxy -help.

Authentication Flags

-credential_file

Specifies the path to a JSON service account key the proxy uses to authorize or authenticate connections.

-token

When set, the proxy uses this Bearer token for authorization.

-enable_iam_login

Enables the proxy to use Cloud SQL IAM database authentication. This will cause the proxy to use IAM account credentials for database user authentication. For details, see Overview of Cloud SQL IAM database authentication. NOTE: This feature only works with Postgres database instances.

Connection Flags

-instances="project1:region:instance1,project3:region:instance1"

A comma-separated list of instances to open inside -dir. Also supports exposing a TCP port and renaming the default Unix Domain Sockets; see examples below. Same list can be provided via INSTANCES environment variable, in case when both are provided - proxy will use command line flag.

Example

Using TCP sockets:

./cloud_sql_proxy -instances=my-project:us-central1:sql-inst=tcp:3306 &
mysql -u root -h 127.0.0.1

Using Unix sockets:

./cloud_sql_proxy -dir=/cloudsql -instances=my-project:us-central1:sql-inst &
mysql -u root -S /cloudsql/my-project:us-central1:sql-inst

To specify a custom Unix socket name:

./cloud_sql_proxy -dir=/cloudsql \
    -instances=my-project:us-central1:sql-inst=unix:custom_socket_name &
mysql -u root -S /cloudsql/custom_socket_name

To specify a custom location for a Unix socket (overrides -dir):

./cloud_sql_proxy -dir=/cloudsql \
    -instances=my-project:us-central1:sql-inst=unix:/my/custom/sql-socket &
mysql -u root -S /my/custom/sql-socket

-fuse

Requires access to /dev/fuse as well as the fusermount binary. An optional -fuse_tmp flag can specify where to place temporary files. The directory indicated by -dir is mounted.

Example

Using -fuse, you do not need to specify instance names ahead of time:

./cloud_sql_proxy -dir=/cloudsql -fuse &
mysql -u root -S /cloudsql/my-project:us-central1:sql-inst

-instances_metadata=metadata_key

Usable on GCE only. The given GCE metadata key will be polled for a list of instances to open in -dir. The metadata key is relative from computeMetadata/v1/. The format for the value is the same as the 'instances' flag. A hanging-poll strategy is used, meaning that changes to the metadata value will be reflected in the -dir even while the proxy is running. When an instance is removed from the list the corresponding socket will be removed from -dir as well (unless it was also specified in -instances), but any existing connections to this instance will NOT be terminated.

Example

./cloud_sql_proxy -dir=/cloudsql \
    -instances_metadata instance/attributes/<custom-metadata-key> &
mysql -u root -S /cloudsql/my-project:us-central1:sql-inst

Note: -instances and -instances_metadata may be used at the same time but are not compatible with the -fuse flag.

-max_connections

If provided, the maximum number of connections to establish before refusing new connections. Defaults to 0 (no limit).

Additional Flags

-ip_address_types=PUBLIC,PRIVATE

A comma-delimited list of preferred IP types for connecting to an instance. For example, setting this to PRIVATE will force the proxy to connect to instances using an instance's associated private IP. Defaults to PUBLIC,PRIVATE

-term_timeout=30s

How long to wait for connections to close after receiving a SIGTERM before shutting down the proxy. Defaults to 0. If all connections close before the duration, the proxy will shutdown early.

-skip_failed_instance_config

Setting this flag will prevent the proxy from terminating if any errors occur during instance configuration. Please note that this means some instances may fail to be set up correctly while others may work if the proxy restarts.

-log_debug_stdout=true

This is to log non-error output to standard out instead of standard error. For example, if you don't want connection related messages to log as errors, set this flag to true. Defaults to false.

-structured_logs

Writes all logging output as JSON with the following keys: severity, timestamp, caller, message and optionally stacktrace. For example, the startup message looks like:

{"severity":"INFO","timestamp":"2020-10-12T07:20:50.52Z","caller":"cloud_sql_proxy/cloud_sql_proxy.go:510","message":"Using gcloud's active project: [my-project-id]"}

-use_http_health_check

Enables HTTP health checks for the proxy, including startup, liveness, and readiness probing. Requires that you configure the Kubernetes container with HTTP probes (instructions).

-health_check_port=8090

Specifies the port that the health check server listens and serves on. Defaults to 8090.

Running as a Kubernetes Sidecar

See the example here as well as Connecting from Google Kubernetes Engine.

Running behind a Socks5 proxy

The Cloud SQL Auth Proxy includes support for sending requests through a SOCKS5 proxy. If a SOCKS5 proxy is running on localhost:8000, the command to start the Cloud SQL Auth Proxy would look like:

ALL_PROXY=socks5://localhost:8000 \
HTTPS_PROXY=socks5://localhost:8000 \
    cloud_sql_proxy -instances=$INSTANCE_CONNECTION_NAME=tcp:5432

The ALL_PROXY environment variable specifies the proxy for all TCP traffic to and from a Cloud SQL instance. The ALL_PROXY environment variable supports socks5 and socks5h protocols. To route DNS lookups through a proxy, use the socks5h protocol.

The HTTPS_PROXY (or HTTP_PROXY) specifies the proxy for all HTTP(S) traffic to the SQL Admin API. Specifying HTTPS_PROXY or HTTP_PROXY is only necessary when you want to proxy this traffic. Otherwise, it is optional. See http.ProxyFromEnvironment for possible values.

Reference Documentation

• Cloud SQL
• Cloud SQL Auth proxy Documentation
• Cloud SQL Auth proxy Quickstarts
• Cloud SQL Code Samples
• Cloud SQL Auth proxy Package Documentation

Support policy

Major version lifecycle

This project uses semantic versioning, and uses the following lifecycle regarding support for a major version:

Active - Active versions get all new features and security fixes (that wouldn’t otherwise introduce a breaking change). New major versions are guaranteed to be "active" for a minimum of 1 year. Deprecated - Deprecated versions continue to receive security and critical bug fixes, but do not receive new features. Deprecated versions will be publicly supported for 1 year. Unsupported - Any major version that has been deprecated for >=1 year is considered publicly unsupported.

Supported Go Versions

We follow the Go Version Support Policy used by Google Cloud Libraries for Go.

Release cadence

The Cloud SQL Auth proxy aims for a minimum monthly release cadence. If no new features or fixes have been added, a new PATCH version with the latest dependencies is released.

Contributing

Contributions are welcome. Please, see the CONTRIBUTING document for details.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See Contributor Code of Conduct for more information.

Third Party

WARNING: These distributions are not officially supported by Google.

Homebrew

There is Homebrew formula for Cloud SQL Auth proxy here.

Kubernetes Cluster Service using Helm

Follow these instructions.

This chart creates a Deployment and a Service, but we recommend deploying the proxy as a sidecar container in your pods.

.Net Proxy Wrapper (Nuget Package)

Install via Nuget, follow these instructions.