Add "How the Cloud SQL Proxy Works" section to README

[runephilosof-karnovgroup]

Bug Description

The error message says port 3307, but I have specified port 5432.

The output from sql proxy

Listening on 127.0.0.1:5432
accepted connection from 127.0.0.1:58436
failed to connect to instance: Dial error: failed to dial (connection name = "xxx"): dial tcp x.x.x.x:3307: i/o timeout

Example code (or command)

From my deployment

      - image: gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.3.0
        name: cloud-sql-proxy
        args:
          - "--private-ip"
          - "--structured-logs"
          - "--port=5432"
          - "--credentials-file=/secrets/credentials.json"
          - "xxx"
        securityContext:
          runAsNonRoot: true
        volumeMounts:
          - name: cloudsql-instance-credentials
            mountPath: /secrets/
            readOnly: true

Stacktrace

No response

Steps to reproduce?

1. Deploy it as a sidecar configured with port 5432, pointing at a server it cannot reach.
2. Connect to it.
3. Wait for the timeout
   ...

Environment

See the example code for the environment

Additional Details

No response

[jackwotherspoon]

Hi @runephilosof-karnovgroup, thanks for raising an issue on the Cloud SQL Proxy 😄

When you run the proxy and specify the port value (5432 in your case) that is setting the port for the local connection. (as seen in below diagram)

The Cloud SQL Proxy that you run is the proxy client, it has a server-side companion that automatically runs and is configured alongside a Cloud SQL instance when it is created. The server-side component listens on port 3307 (TCP standard port in diagram above) of your Cloud SQL instance’s IP address for incoming connections from the client.

This is what you are seeing in the error message. The connection to your instance's IP address on port 3307 is timing out. (most likely caused by a network path issue, as you mentioned the server can not be reached) I will discuss with our team and see if this error message can be improved to make this more clear. We are also looking to add a more detailed version of the diagram to our README in hopes that helps as well.

Diagram is from How the Cloud SQL Auth Proxy works

[jackwotherspoon]

@runephilosof-karnovgroup I have change this issue to track adding a similar "How the Cloud SQL Proxy Works" section from our official Google Cloud docs to our README with the diagram above. I think a lot of people would benefit from this.

Thanks for getting this jump started!

Have a great day - Jack

[sean-conkie]

Hi @jackwotherspoon - hope it's ok to add here; the migration guide states different ports to 3307 (from the "How the Cloud SQL Proxy Works" section).

# v2
# Using automatic database port selection (MySQL 3306, Postgres 5432, SQL Server 1433)
./cloud-sql-proxy <INSTANCE_CONNECTION_NAME>

Does this need updated, or am I miss understanding what it's saying?

[runephilosof-karnovgroup]

Also

cloud-sql-proxy/cmd/root.go

Line 151 in 51cc2c6

from there (e.g., 3306, 3307, 3308, etc). To disable this behavior (and

adds to the confusion.
Since 3307 is actually sometimes used for MySQL for the local connection proxy client if you do not specify a port and it detects MySQL (if I understand it correctly).

So maybe the server side proxy component should be using a port number that does not resemble any of the ports normally used by the databases (are the proxy components using ssh, then maybe just 22 or a port number resembling ssh, for instance 2222).

[jackwotherspoon]

@sean-conkie Absolutely okay to add I can hopefully clarify for you. @runephilosof-karnovgroup I will answer your confusion here too.

There seems to be a bit of confusion and hopefully this will be more clear once we add this new section to the docs with the diagram etc.

The ports that you both have referenced ("MySQL 3306, Postgres 5432, SQL Server 1433", and "3306, 3307, 3308") are all for the local connection. So when you run the Cloud SQL Proxy locally it binds one or several of these ports (depending on type of database and how many instances you are configuring) to your localhost.

So if I run the following:

# starts the Proxy listening on localhost with the default database engine port
# For example:
#   MySQL      127.0.0.1:3306
#   Postgres   127.0.0.1:5432
#   SQL Server 127.0.0.1:1433
./cloud-sql-proxy <INSTANCE_CONNECTION_NAME>

As per the comment it will bind and begin listening for connections on 127.0.0.1:3306 for MySQL, 127.0.0.1:5432 for Postgres etc. Again it is important to keep in mind that these ports are on your localhost. You can see this is working as expected in the initial description because of the line:

Listening on 127.0.0.1:5432

The issue with port 3307 you are seeing is not on the local connection, it's happening on the Cloud SQL instance on port 3307. This is where the confusion lies, these are two very different things. The Cloud SQL Proxy forwards the local connections to the Cloud SQL instance's IP on port 3307 (TCP standard port in diagram above), this is done internally as part of the Cloud SQL Proxy (which uses Cloud SQL Go Connector, see code here where server port is configured). You can have something bound to port 3307 on your local connection and it will not interfere with the remote connection port as these are two separate IP addresses on different servers. I hope this makes a bit of sense.

This is the error you are seeing: dial tcp x.x.x.x:3307: i/o timeout, x.x.x.x is hiding your Cloud SQL instance IP address. The issue is on establishing the connection to your Cloud SQL instance IP address on the Cloud SQL server, the local connection is working fine.