Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: update README with rendered notices #2227

Merged
merged 1 commit into from
May 23, 2024
Merged

chore: update README with rendered notices #2227

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 40 additions & 31 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,10 +32,12 @@ connector which does everything the Proxy does, but in process:
For users migrating from v1, see the [Migration Guide](migration-guide.md).
The [v1 README][v1 readme] is still available.

NOTE: The Proxy does not configure the network between the VM it's running on
and the Cloud SQL instance. You MUST ensure the Proxy can reach your Cloud SQL
instance, either by deploying it in a VPC that has access to your Private IP
instance, or by configuring Public IP.
> [!IMPORTANT]
>
> The Proxy does not configure the network between the VM it's running on
> and the Cloud SQL instance. You MUST ensure the Proxy can reach your Cloud SQL
> instance, either by deploying it in a VPC that has access to your Private IP
> instance, or by configuring Public IP.

[cloud monitoring]: https://cloud.google.com/monitoring
[cloud trace]: https://cloud.google.com/trace
Expand Down Expand Up @@ -187,19 +189,21 @@ The Cloud SQL Proxy uses a Cloud IAM principal to authorize connections against
a Cloud SQL instance. The Proxy sources the credentials using
[Application Default Credentials](https://cloud.google.com/docs/authentication/production).

Note: Any IAM principal 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][roles-and-permissions] for details.
> [!NOTE]
>
> Any IAM principal 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][roles-and-permissions] 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.,
Expand Down Expand Up @@ -293,9 +297,11 @@ private IP, use:
./cloud-sql-proxy --private-ip <INSTANCE_CONNECTION_NAME>
```

NOTE: The Proxy does not configure the network. You MUST ensure the Proxy can
reach your Cloud SQL instance, either by deploying it in a VPC that has access
to your Private IP instance, or by configuring Public IP.
> [!IMPORTANT]
>
> The Proxy does not configure the network. You MUST ensure the Proxy can
> reach your Cloud SQL instance, either by deploying it in a VPC that has access
> to your Private IP instance, or by configuring Public IP.

### Configuring Unix domain sockets

Expand All @@ -321,14 +327,16 @@ query param:
'myproject:my-region:mysql?unix-socket=/cloudsql'
```

NOTE: The Proxy supports Unix domain sockets on recent versions of Windows, but
replaces colons with periods:

```shell
# Starts a Unix domain socket at the path:
# C:\cloudsql\myproject.my-region.mysql
./cloud-sql-proxy --unix-socket C:\cloudsql myproject:my-region:mysql
```
> [!NOTE]
>
> The Proxy supports Unix domain sockets on recent versions of Windows, but
> replaces colons with periods:
>
> ```shell
> # Starts a Unix domain socket at the path:
> # C:\cloudsql\myproject.my-region.mysql
> ./cloud-sql-proxy --unix-socket C:\cloudsql myproject:my-region:mysql
> ```

### Testing Connectivity

Expand Down Expand Up @@ -445,9 +453,10 @@ with `chgrp 65532 key.json && chmod g+r key.json`.
1. If you can't control your file's group, you can directly change the public
permissions of your file by doing `chmod o+r key.json`.

> [!WARNING]
> This can be insecure because it allows any user in the host system to read
> the credential file which they can use to authenticate to services in GCP.
> [!WARNING]
>
> This can be insecure because it allows any user in the host system to read
> the credential file which they can use to authenticate to services in GCP.

For example, a full command using a JSON credentials file might look like

Expand Down
Loading