1# Cloud SQL Auth proxy
2
3![CI][ci-badge]
4[![Go Reference][pkg-badge]][pkg-docs]
5
6The [Cloud SQL Auth proxy][proxy-page] is a binary that provides IAM-based
7authorization and encryption when connecting to a Cloud SQL instance.
8
9See the [Connecting Overview][connection-overview] page for more information on
10connecting to a Cloud SQL instance, or the [About the proxy][about-proxy] page
11for details on how the Cloud SQL proxy works.
12
13Note: The Proxy *cannot* provide a network path to a Cloud SQL instance if one
14is not already present (e.g., the proxy cannot access a VPC if it does not
15already have access to it).
16
17## Installation
18
19For 64-bit Linux, run:
20
21```
22VERSION=v1.21.0 # see Releases for other versions
23wget "https://storage.googleapis.com/cloudsql-proxy/$VERSION/cloud_sql_proxy.linux.amd64" -O cloud_sql_proxy
24chmod +x cloud_sql_proxy
25```
26
27Releases for additional OS's and architectures and be found on the [releases
28page][releases].
29
30For alternative distributions, see below under [third party](#third-party).
31
32### Container Images
33
34There are containerized versions of the proxy available from the following
35Google Cloud Container Registry repositories:
36
37* `gcr.io/cloudsql-docker/gce-proxy`
38* `us.gcr.io/cloudsql-docker/gce-proxy`
39* `eu.gcr.io/cloudsql-docker/gce-proxy`
40* `asia.gcr.io/cloudsql-docker/gce-proxy`
41
42Each image is tagged with the associated proxy version. The following tags are
43currently supported:
44
45* `$VERSION` - default image (recommended)
46* `$VERSION-alpine` - uses [`alpine:3`](https://hub.docker.com/_/alpine)
47 as a base image (only supported from v1.17 up)
48* `$VERSION-buster` - uses [`debian:buster`](https://hub.docker.com/_/debian)
49 as a base image (only supported from v1.17 up)
50
51We recommend using the latest version of the proxy and updating the version
52regularly. However, we also recommend pinning to a specific tag and avoid the
53latest tag. Note: the tagged version is only that of the proxy. Changes in base
54images may break specific setups, even on non-major version increments. As such,
55it's a best practice to test changes before deployment, and use automated
56rollbacks to revert potential failures.
57
58### Install from Source
59
60To install from source, ensure you have the latest version of [Go
61installed](https://golang.org/doc/install).
62
63Then, simply run:
64
65```
66go get github.com/GoogleCloudPlatform/cloudsql-proxy/cmd/cloud_sql_proxy
67```
68
69The `cloud_sql_proxy` will be placed in `$GOPATH/bin` after `go get` completes.
70
71## Usage
72
73All the following invocations assume valid credentials are present in the
74environment. The following examples all reference an `INSTANCE_CONNECTION_NAME`,
75which takes the form: `myproject:myregion:myinstance`. To find the
76`INSTANCE_CONNECTION_NAME`, run `gcloud sql instances describe <INSTANCE_NAME>`
77where `INSTANCE_NAME` is the name of the database instance.
78
79### TCP socket example
80
81``` bash
82# Starts the proxy listening on 127.0.0.1:5432
83cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:5432
84```
85
86``` bash
87# Starts the proxy listening on port 5432 on *all* interfaces
88cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:0.0.0.0:5432
89```
90
91### Unix socket example
92
93``` bash
94# The proxy will mount a Unix domain socket at /cloudsql/<INSTANCE_CONNECTION_NAME>
95# Note: The directory specified by `-dir` must exist and the socket file path
96# (i.e., dir plus INSTANCE_CONNECTION_NAME) must be under your platform's
97# limit (typically 108 characters on many Unix systems, but varies by platform).
98cloud_sql_proxy -dir=/cloudsql -instances=<INSTANCE_CONNECTION_NAME>
99```
100
101### Private IP example
102
103```
104cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:5432 -ip_address_types=PRIVATE
105```
106
107In order to connect using Private IP, you must have access through your
108project's VPC. For more details, see [Private IP Requirements][private-ip].
109
110## Credentials
111
112The Cloud SQL proxy uses a Cloud IAM account to authorize connections against a
113Cloud SQL instance. The proxy sources the credentials for these accounts in the
114following order:
115
1161. The `-credential_file` flag
1172. The `-token` flag
1183. The service account key at the path stored in the
119 `GOOGLE_APPLICATION_CREDENTIALS` environment variable.
1204. The gcloud user credentials (set from `gcloud auth login`)
1215. The [Application Default Credentials](https://cloud.google.com/docs/authentication/production)
122
123Note: Any account connecting to a Cloud SQL database will need one of the
124following IAM roles:
125
126- Cloud SQL Client (preferred)
127- Cloud SQL Editor
128- Cloud SQL Admin
129
130Or one may manually assign the following IAM permissions:
131
132- `cloudsql.instances.connect`
133- `cloudsql.instances.get`
134
135See [Roles and Permissions in Cloud SQL][roles-and-permissions] for details.
136
137When the proxy authenticates under the Compute Engine VM's default service
138account, the VM must have at least the `sqlservice.admin` API scope (i.e.,
139"https://www.googleapis.com/auth/sqlservice.admin") and the associated project
140must have the SQL Admin API enabled. The default service account must also have
141at least writer or editor privileges to any projects of target SQL instances.
142
143
144## CLI Flags
145
146The Cloud SQL Auth proxy takes a few arguments to configure what instances to connect
147to and connection behavior. For a full list of flags supported by the proxy,
148use `cloud_sql_proxy -help`.
149
150### Authentication Flags
151
152#### `-credential_file`
153
154Specifies the path to a JSON [service account][service-account] key the proxy
155uses to authorize or authenticate connections.
156
157#### `-token`
158
159When set, the proxy uses this Bearer token for authorization.
160
161#### `-enable_iam_login`
162
163Enables the proxy to use Cloud SQL IAM database authentication. This will cause
164the proxy to use IAM account credentials for database user authentication. For
165details, see [Overview of Cloud SQL IAM database authentication][iam-auth].
166NOTE: This feature only works with Postgres database instances.
167
168### Connection Flags
169
170#### `-instances="project1:region:instance1,project3:region:instance1"`
171
172A comma-separated list of instances to open inside `-dir`. Also supports
173exposing a TCP port and renaming the default Unix Domain Sockets; see examples
174below. Same list can be provided via INSTANCES environment variable, in case
175when both are provided - proxy will use command line flag.
176
177**Example**
178
179Using TCP sockets:
180
181```
182./cloud_sql_proxy -instances=my-project:us-central1:sql-inst=tcp:3306 &
183mysql -u root -h 127.0.0.1
184```
185
186Using Unix sockets:
187
188```
189./cloud_sql_proxy -dir=/cloudsql -instances=my-project:us-central1:sql-inst &
190mysql -u root -S /cloudsql/my-project:us-central1:sql-inst
191```
192
193To specify a custom Unix socket name:
194
195```
196./cloud_sql_proxy -dir=/cloudsql \
197 -instances=my-project:us-central1:sql-inst=unix:custom_socket_name &
198mysql -u root -S /cloudsql/custom_socket_name
199```
200
201To specify a custom location for a Unix socket (overrides `-dir`):
202
203```
204./cloud_sql_proxy -dir=/cloudsql \
205 -instances=my-project:us-central1:sql-inst=unix:/my/custom/sql-socket &
206mysql -u root -S /my/custom/sql-socket
207```
208
209#### `-fuse`
210
211Requires access to `/dev/fuse` as well as the `fusermount` binary. An optional
212`-fuse_tmp` flag can specify where to place temporary files. The directory
213indicated by `-dir` is mounted.
214
215**Example**
216
217Using `-fuse`, you do not need to specify instance names ahead of time:
218
219```
220./cloud_sql_proxy -dir=/cloudsql -fuse &
221mysql -u root -S /cloudsql/my-project:us-central1:sql-inst
222```
223
224#### `-instances_metadata=metadata_key`
225
226Usable on [GCE](https://cloud.google.com/compute/docs/quickstart) only. The
227given [GCE metadata](https://cloud.google.com/compute/docs/metadata) key will be
228polled for a list of instances to open in `-dir`. The metadata key is relative
229from `computeMetadata/v1/`. The format for the value is the same as the
230'instances' flag. A hanging-poll strategy is used, meaning that changes to the
231metadata value will be reflected in the `-dir` even while the proxy is running.
232When an instance is removed from the list the corresponding socket will be
233removed from `-dir` as well (unless it was also specified in `-instances`), but
234any existing connections to this instance will NOT be terminated.
235
236**Example**
237
238```
239./cloud_sql_proxy -dir=/cloudsql \
240 -instances_metadata instance/attributes/<custom-metadata-key> &
241mysql -u root -S /cloudsql/my-project:us-central1:sql-inst
242```
243
244Note: `-instances` and `-instances_metadata` may be used at the same time but
245are not compatible with the `-fuse` flag.
246
247#### `-max_connections`
248
249If provided, the maximum number of connections to establish before refusing new
250connections. Defaults to 0 (no limit).
251
252### Additional Flags
253
254#### `-ip_address_types=PUBLIC,PRIVATE`
255
256A comma-delimited list of preferred IP types for connecting to an instance. For
257example, setting this to PRIVATE will force the proxy to connect to instances
258using an instance's associated private IP. Defaults to `PUBLIC,PRIVATE`
259
260#### `-term_timeout=30s`
261
262How long to wait for connections to close before shutting down the proxy.
263Defaults to 0.
264
265#### `-skip_failed_instance_config`
266
267Setting this flag will prevent the proxy from terminating if any errors occur
268during instance configuration. Please note that this means some instances may
269fail to be set up correctly while others may work if the proxy restarts.
270
271#### `-log_debug_stdout=true`
272
273This is to log non-error output to standard out instead of standard error. For
274example, if you don't want connection related messages to log as errors, set
275this flag to true. Defaults to false.
276
277#### `-structured_logs`
278
279Writes all logging output as JSON with the following keys: severity, timestamp, caller,
280message and optionally stacktrace. For example, the startup message looks like:
281
282```json
283{"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]"}
284```
285
286#### `-use_http_health_check`
287
288Enables HTTP health checks for the proxy, including startup, liveness, and readiness probing.
289Requires that you configure the Kubernetes container with HTTP probes ([instructions][health-check-example]).
290
291#### `-health_check_port=8090`
292
293Specifies the port that the health check server listens and serves on. Defaults to 8090.
294
295## Running as a Kubernetes Sidecar
296
297See the [example here][sidecar-example] as well as [Connecting from Google
298Kubernetes Engine][connect-to-k8s].
299
300## Running behind a Socks5 proxy
301
302The Cloud SQL Auth Proxy includes support for sending requests through a SOCKS5
303proxy. If a SOCKS5 proxy is running on `localhost:8000`, the command to start
304the Cloud SQL Auth Proxy would look like:
305
306```
307ALL_PROXY=socks5://localhost:8000 \
308HTTPS_PROXY=socks5://localhost:8000 \
309 cloud_sql_proxy -instances=$INSTANCE_CONNECTION_NAME=tcp:5432
310```
311
312The `ALL_PROXY` environment variable specifies the proxy for all TCP
313traffic to and from a Cloud SQL instance. The `ALL_PROXY` environment variable
314supports `socks5` and `socks5h` protocols. To route DNS lookups through a proxy,
315use the `socks5h` protocol.
316
317The `HTTPS_PROXY` (or `HTTP_PROXY`) specifies the proxy for all HTTP(S) traffic
318to the SQL Admin API. Specifying `HTTPS_PROXY` or `HTTP_PROXY` is only necessary
319when you want to proxy this traffic. Otherwise, it is optional. See
320[`http.ProxyFromEnvironment`](https://pkg.go.dev/net/http@go1.17.3#ProxyFromEnvironment)
321for possible values.
322
323## Reference Documentation
324
325- [Cloud SQL][cloud-sql]
326- [Cloud SQL Auth proxy Documentation][proxy-page]
327- [Cloud SQL Auth proxy Quickstarts][quickstarts]
328- [Cloud SQL Code Samples][code-samples]
329- [Cloud SQL Auth proxy Package Documentation][pkg-docs]
330
331## Support policy
332
333### Major version lifecycle
334
335This project uses [semantic versioning](https://semver.org/), and uses the
336following lifecycle regarding support for a major version:
337
338**Active** - Active versions get all new features and security fixes (that
339wouldn’t otherwise introduce a breaking change). New major versions are
340guaranteed to be "active" for a minimum of 1 year.
341**Deprecated** - Deprecated versions continue to receive security and critical
342bug fixes, but do not receive new features. Deprecated versions will be publicly
343supported for 1 year.
344**Unsupported** - Any major version that has been deprecated for >=1 year is
345considered publicly unsupported.
346
347### Release cadence
348The Cloud SQL Auth proxy aims for a minimum monthly release cadence. If no new
349features or fixes have been added, a new PATCH version with the latest
350dependencies is released.
351
352## Contributing
353
354Contributions are welcome. Please, see the [CONTRIBUTING][contributing] document
355for details.
356
357Please note that this project is released with a Contributor Code of Conduct.
358By participating in this project you agree to abide by its terms. See
359[Contributor Code of Conduct][code-of-conduct] for more information.
360
361## Third Party
362
363__WARNING__: _These distributions are not officially supported by Google._
364
365### Homebrew
366
367There is Homebrew formula for Cloud SQL Auth proxy [here](https://github.com/tclass/homebrew-cloud_sql_proxy).
368
369### Kubernetes Cluster Service using Helm
370
371Follow these [instructions](https://github.com/rimusz/charts/tree/master/stable/gcloud-sqlproxy).
372
373This chart creates a Deployment and a Service, but we recommend deploying the
374proxy as a sidecar container in your pods.
375
376### .Net Proxy Wrapper (Nuget Package)
377
378Install via Nuget, follow these
379[instructions](https://github.com/expert1-pty-ltd/cloudsql-proxy#install-via-nuget).
380
381
382[about-proxy]: https://cloud.google.com/sql/docs/mysql/sql-proxy
383[ci-badge]: https://storage.googleapis.com/cloud-devrel-public/cloud-sql-connectors/proxy/go1.17_linux.svg
384[cloud-sql]: https://cloud.google.com/sql
385[code-samples]: https://cloud.google.com/sql/docs/mysql/samples
386[code-of-conduct]: CONTRIBUTING.md#contributor-code-of-conduct
387[connect-to-k8s]: https://cloud.google.com/sql/docs/mysql/connect-kubernetes-engine
388[connection-overview]: https://cloud.google.com/sql/docs/mysql/connect-overview
389[contributing]: CONTRIBUTING.md
390[health-check-example]: https://github.com/GoogleCloudPlatform/cloudsql-proxy/tree/main/examples/k8s-health-check#cloud-sql-proxy-health-checks
391[iam-auth]: https://cloud.google.com/sql/docs/postgres/authentication
392[pkg-badge]: https://pkg.go.dev/badge/github.com/GoogleCloudPlatform/cloudsql-proxy.svg
393[pkg-docs]: https://pkg.go.dev/github.com/GoogleCloudPlatform/cloudsql-proxy
394[private-ip]: https://cloud.google.com/sql/docs/mysql/private-ip#requirements_for_private_ip
395[proxy-page]: https://cloud.google.com/sql/docs/mysql/sql-proxy
396[quickstarts]: https://cloud.google.com/sql/docs/mysql/quickstarts
397[releases]: https://github.com/GoogleCloudPlatform/cloudsql-proxy/releases
398[roles-and-permissions]: https://cloud.google.com/sql/docs/mysql/roles-and-permissions
399[service-account]: https://cloud.google.com/iam/docs/service-accounts
400[sidecar-example]: https://github.com/GoogleCloudPlatform/cloudsql-proxy/tree/master/examples/k8s-sidecar#run-the-cloud-sql-proxy-as-a-sidecar
401[source-install]: docs/install-from-source.md
View as plain text