DEV Community: Edgar

Cloud SQL's new default has no IP address. Reaching it from a Mac through IAP

Edgar — Mon, 09 Nov 2026 17:00:02 +0000

Since 13 October 2026, a Cloud SQL instance created in a new project gets Private Service Connect as its private connectivity unless you choose private services access or both. Ask the Admin API about such an instance and the response has no ipAddresses field. It has a dnsName that ends in a dot and a pscServiceAttachmentLink, and nothing you could hand to psql.

Two days after the change I created a throwaway PSC instance in a demo project to see what my own app would do with it. Its Cloud SQL table showed a dash in the Private IP column, and Open Tunnel did nothing.

An instance on the older private services access setup does show an address, something like 10.50.0.7, and a laptop can't reach that one either. Both kinds need a machine inside Google's network that can reach the database, and with IAP that machine doesn't need an external IP.

Why the Cloud SQL Auth Proxy on a laptop times out

With private services access the instance runs in a VPC that Google manages, peered to yours. Your laptop has no route into either. Peering isn't transitive, so a VM in a second VPC peered to yours can't get to the database through it.

The proxy's README says it under --private-ip: "there must be a network path present for this to work." Google's connection page says the proxy "must be on a resource with access to the same VPC network as the instance." Run it on a Mac, or in Cloud Shell, which isn't in your VPC either, and it times out dialing port 3307, the port the proxy connects to on the instance:

dial tcp 10.127.0.4:3307: connect: connection timed out

Start it without --private-ip against an instance that has no public IP and it fails earlier, with Config error: instance does not have IP of type "PUBLIC".

--sql-data is described as "Enable SQL Data to tunnel through the Cloud SQL Admin API without needing network access to your public or private IP". It came with the change titled "Support Developer Edition connections", and the commit message says Developer Edition instances allow connections through the SqlDataService. Nothing I found says it works for other editions, so for a production instance I'd still plan on a network path.

A PSC-only instance needs an endpoint in your VPC

PSC has no peering. The instance publishes a service attachment, and you reach it through an endpoint in your own VPC, which is an internal IP address on a forwarding rule whose target is that service attachment. You reserve the address and create the endpoint yourself, or a service connection policy creates it. Since 27 August the instance creation flow can also create the policy and the endpoint for you, if you ask it to.

The project that holds the endpoint has to be on the instance's allowlist (pscConfig.allowedConsumerProjects; Google asks for at least one project). An endpoint in a project that isn't on the list stays PENDING.

If someone else set up the instance and you're looking for its endpoint, start from the instance. Its pscServiceAttachmentLink is what the endpoint's forwarding rule names as target, so look through the forwarding rules in the instance's project and in each allowed consumer project. The two APIs spell the link differently: Cloud SQL returns a relative path starting with projects/, Compute returns a full URL, so a script has to compare from projects/ on. The rule you find gives you two things: the IP to forward to, and the VPC your bastion has to be on.

Google recommends connecting to a PSC instance by its DNS name, and the Auth Proxy requires the DNS name. That means a private DNS record for dnsName on the bastion's VPC. An SSH forward to the endpoint IP works without one.

Route 1: an SSH forward through a bastion over IAP

The IAP hop needs the same things for both routes:

an ingress firewall rule from 35.235.240.0/20 on tcp:22 (2600:2d00:1:7::/64 for IPv6)
roles/iap.tunnelResourceAccessor for whoever connects
SSH access to the VM, through OS Login or a key in metadata
a VM on the instance's VPC, or on the VPC that holds the PSC endpoint. It needs no external IP; IAP connects to the primary internal address of nic0.

gcloud compute ssh bastion-01 --tunnel-through-iap \
    --zone=europe-west1-b --project=acme-prod \
    -- -N -L 5432:10.50.0.7:5432
psql "host=127.0.0.1 port=5432 user=postgres dbname=orders sslmode=require"

For a PSC instance, put the endpoint IP where 10.50.0.7 is. --tunnel-through-iap makes gcloud go through IAP even when the VM has an external IP; without the flag it uses IAP only for a VM that has none.

Nothing here talks to the Cloud SQL API, so you need no Cloud SQL role, and the database checks its own user and password. Keep sslmode=require, or verify-ca with the server CA. verify-full, and VERIFY_IDENTITY on MySQL, fail because the client is connecting to 127.0.0.1.

An instance that enforces the Cloud SQL connectors for every connection refuses this.

Route 2: the Auth Proxy on the bastion, listening on loopback

On the bastion:

./cloud-sql-proxy --private-ip --port 5432 acme-prod:europe-west1:orders-db
# PSC instance:
./cloud-sql-proxy --psc --port 5432 acme-prod:europe-west1:orders-db

From the Mac, forward to the bastion's own loopback:

gcloud compute ssh bastion-01 --tunnel-through-iap --zone=europe-west1-b \
    --project=acme-prod -- -N -L 5432:127.0.0.1:5432

The proxy binds 127.0.0.1 by default. On Stack Overflow the accepted fix for "the proxy on my bastion is unreachable" is --address 0.0.0.0, which opens the database port on the VM's network interface. With the forward pointed at 127.0.0.1 on the bastion, you can leave the default alone.

This route costs more: a binary and a service on the VM, the Cloud SQL Admin API enabled, and roles/cloudsql.client for the identity the proxy runs as, here the bastion's service account. For that you get IAM-authorized TLS to the instance, and it works when the instance enforces connectors. A PSC instance still needs the endpoint and the record on the bastion's VPC.

What I built for this

I manage VMs in more than ten Google Cloud organizations from a Mac, and before I built Ostgate the commands above lived in aliases and scripts. Ostgate does route 1 without gcloud. Open Tunnel on an instance targets its private IP on the engine's port, offers a running VM on the instance's VPC as the bastion, and forwards 127.0.0.1 through that VM over one SSH session carried by IAP.

For a PSC instance it runs the search from the endpoint section. In the test run before the release, I created a throwaway PSC instance and it showed "no endpoint"; after I created an endpoint in prod-vpc, the cell showed 10.10.0.12, bastion-01 was preselected, and the server answered an SSLRequest through 127.0.0.1:5432.

The Cloud SQL tab. These instances use private services access; a PSC instance shows its endpoint address in the same column.

With no endpoint, Open Tunnel stays off and names the projects it searched. Ostgate never creates endpoints, addresses or DNS records. It doesn't speak the Auth Proxy protocol, so an instance that enforces connectors refuses it like any direct connection, and it needs a running VM you can SSH to. The setup and its limits are in the guide: https://ostgate.app/guides/cloud-sql-private-ip-mac

I build Ostgate, a paid macOS app with a 7-day trial. It isn't affiliated with Google.

IAP Desktop for Mac: how I reach GCP VMs with no public IP, without gcloud

Edgar — Thu, 05 Nov 2026 09:46:15 +0000

Originally published in Google Cloud - Community.

I work across a lot of Google Cloud projects and accounts from a MacBook. Most of the VMs have no public IP, which is how it should be: Identity-Aware Proxy (IAP) lets you reach them through Google instead of through a bastion or a VPN.

On Windows, Google's answer is IAP Desktop, an open-source client with SSH and Remote Desktop tabs. There is no Mac version, and the GitHub issue asking for one sat open for years. On a Mac you get gcloud, a terminal, and a separate RDP app pointed at localhost.

This post covers how IAP TCP forwarding works, how to do everything with gcloud for free, where that gets painful, and the native client I ended up building.

How IAP TCP forwarding works

Your Mac never talks to the VM directly. Google's relay does, from a fixed range.

A tunnel is a WebSocket over TLS to tunnel.cloudproxy.app. Your Google account's token rides along, and the relay checks that the account has roles/iap.tunnelResourceAccessor (IAP-secured Tunnel User) on the project or the instance. If it does, the relay opens an ordinary TCP connection to the VM's internal address, from the range 35.235.240.0/20.

Two things follow from that:

The VM needs nothing installed and no public IP. It only needs a firewall rule that lets 35.235.240.0/20 in on the ports you use.
Every TCP connection is its own WebSocket. A "tunnel" on your laptop is a listener on 127.0.0.1 that opens a new relay session for each socket it accepts. Ten SSH sessions through one tunnel are ten WebSockets.

The setup, once per project

The firewall rule (22 for SSH, 3389 for RDP):

gcloud compute firewall-rules create allow-iap-ingress \
    --project=acme-prod --network=default \
    --direction=INGRESS --action=allow \
    --rules=tcp:22,tcp:3389 \
    --source-ranges=35.235.240.0/20

The role for each person who connects:

gcloud projects add-iam-policy-binding acme-prod \
    --member=user:alice@example.com \
    --role=roles/iap.tunnelResourceAccessor

That is all IAP needs. The same setup serves IAP Desktop, gcloud and any other IAP client.

The free route on a Mac

SSH is one command:

gcloud compute ssh example-vm \
    --project=acme-prod --zone=europe-west1-b \
    --tunnel-through-iap

Files go through the same tunnel:

gcloud compute scp ./backup.tar.gz example-vm:~/ \
    --tunnel-through-iap --zone=europe-west1-b --project=acme-prod

Remote Desktop to a Windows VM takes two steps. First a Windows password, then a tunnel that you leave running while an RDP client such as Microsoft's Windows App connects to localhost:33389:

gcloud compute reset-windows-password win-01 \
    --zone=europe-west1-b --project=acme-prod --user=northwind

gcloud compute start-iap-tunnel win-01 3389 \
    --local-host-port=localhost:33389 \
    --zone=europe-west1-b --project=acme-prod

A database works the same way: start-iap-tunnel to port 5432, and your SQL client connects to the local port.

This all works, and it costs nothing. Step-by-step versions with screenshots are in the RDP guide and the firewall and IAM guide.

Where it got painful for me

Before: one terminal per tunnel. After: one window.

The commands are fine one at a time. My day looked different:

Several accounts. gcloud has one active account per configuration, and gcloud config set account does not move Application Default Credentials, so client libraries keep using the old account. Two tunnels as two accounts means two gcloud processes.
A terminal tab per start-iap-tunnel, and remembering which local port maps to which VM.
Remote Desktop in one app, SSH in another, files in a third.
Sleep and Wi-Fi changes. The tunnels came back slowly or not at all after the lid had been closed.

None of this is a bug in gcloud. It is a CLI, and I wanted a window.

What I built

Ostgate is a native macOS app that opens IAP tunnels itself, without gcloud. You sign in with a Google account in your browser and it lists the projects and VMs that account can reach. Several accounts can be signed in side by side.

VMs from two accounts in one table.

Remote Desktop

Remote Desktop runs inside the window. Ostgate asks for or generates the Windows password through the guest agent, opens the tunnel and connects:

From the VM list to a Windows desktop, over IAP.

Clipboard sync, a Mac folder shared as a Windows drive, and a desktop that resizes with the window.

SSH and files

SSH opens in tabs, with keys generated in the Mac's Secure Enclave and published through OS Login or instance metadata. Appliances without OS Login can use a password or a key file of your own.

Every SSH instance also has a Files tab, an SFTP browser. You navigate, create folders, rename and delete, and drag files in from Finder and out to it:

Folders go up in one go; folders and several files come down as one ZIP.

The parts I wanted most from scp and never had:

A whole folder uploads in one step, and a folder or a multi-file selection downloads as one ZIP. When an instance has no GNU tar or allows SFTP only, the files go over SFTP several at a time instead, and the app says why.
Transfers run in the background with progress and Cancel. A cancelled or failed transfer never leaves half a file behind.
A Files tab that loses its connection shows Reconnect and comes back in the same folder.

The Files tab on a VM with no public IP.

Tunnels and port forwarding

This is the part that replaced most of my terminal tabs. A tunnel maps a port on the VM to 127.0.0.1 on the Mac:

A PostgreSQL tunnel, from the VM's menu to a listening port.

Any port, with presets for SSH, RDP, PostgreSQL, MySQL, SQL Server, Redis and HTTP(S). The local port stays the same between runs, so saved connections in a database client keep working.
Copy Command puts the client's command line on the clipboard; web tunnels open in the browser.
A tunnel can start with its account, keeps running when the window is closed, and sits in the menu bar. After a Wi-Fi drop or sleep it dials again as soon as the network is back.
Ports below 1024 work. A forward can listen on 443 or 22 under a host name of your choice: each alias gets its own loopback address between 127.0.0.2 and 127.0.0.254, so two forwards can both use 443. A small helper that you allow once in System Settings binds those ports.

Some targets are not VMs at all. A forward profile carries several forwards over one SSH session to anything a VM can reach, such as an internal load balancer or a private database, and can add /etc/hosts aliases while it runs. Cloud SQL instances on a private IP open through one of your running VMs, with no separate proxy VM. Internal-only Cloud Run services and functions open in the browser through a local proxy.

Tunnels and forward profiles, each with the account it runs as.

Terminal still matters, so one click adds an SSH config block. After that, ssh, scp, rsync and an IDE's Remote-SSH reach a VM by a predictable name, even with Ostgate's window closed:

ssh example-vm.europe-west1-b.acme-prod.gcp
rsync -avP ./releases/ example-vm.europe-west1-b.acme-prod.gcp:~/releases/

Three things that were harder than they look

The protocol is not documented. Google documents how to use IAP, not what goes over the wire. The source of gcloud and of IAP Desktop is the specification: a binary framing with data chunks up to 16 KiB and acknowledgements that count bytes, plus a reconnect endpoint that resumes a session from the last acknowledged byte. Both clients agree on it, and Google can change it, so the client has to tolerate messages it does not know.

Waking up. After sleep, every SSH, RDP and database connection is its own WebSocket and has to come back on its own. My first retry loop never gave up on a dead network: a dial counted as successful before the WebSocket upgrade had finished, and the failure that came later restarted the loop with a fresh counter. A dial now means the upgrade completed, with a 15-second handshake deadline and backoff from 1.5 to 20 seconds.

The local port is a door. A listener on 127.0.0.1 accepts any process on the Mac, not only yours. Ostgate checks which process is on the other end of every connection before wiring it to IAP. By default only Ostgate itself gets through; you can allow your own processes, or any local process after a confirmation.

When something fails

IAP reports failures as WebSocket close codes. The three that cover most cases:

Code	What it means	Usual fix
4033	The account lacks the IAP tunnel role	Grant `roles/iap.tunnelResourceAccessor`
4003	IAP could not reach the port on the VM	Firewall rule for `35.235.240.0/20`, VM running, service listening
4047	The instance or zone lookup failed	Check the name, zone and network interface

The full table with gcloud's error messages is in IAP tunnel errors.

Where IAP Desktop still does more

IAP Desktop is free and open source, and it does things Ostgate does not: RDP redirection of microphones, printers and smart cards, joining a VM to Active Directory, certificate-based access, connections over VPN or Interconnect, and central policy through group policies. If you are on Windows, use it.

Try it

Ostgate runs on Apple Silicon Macs with macOS 15 or later. It has a 7-day trial with no sign-up, then it is paid. It does not route anything through a server of mine: the app talks to Google as you, tokens stay in the macOS Keychain, and there is no telemetry.

A side-by-side comparison with IAP Desktop is at ostgate.app/iap-desktop-mac.

I'm the developer of Ostgate. Not affiliated with Google. Drafted with AI assistance and edited by me.

RDP to a Windows VM over IAP: serial port 4, NLA and a certificate nobody checks

Edgar — Mon, 02 Nov 2026 08:52:46 +0000

Originally published in Google Cloud - Community.

Google's page on connecting to Windows VMs has a section called "Verify the RDP certificate". You read serial port 1 from the VM's first boot, find a line like the one below, and compare the thumbprint with the certificate your RDP client is shown.

GCEInstanceSetup: RDP certificate details: Subject: CN=rdp-test, Thumbprint: <40 hex characters>

I tried it on a Windows Server 2025 VM in an organization I work with, a month after it was created. Serial port 1 held 27,597 bytes, all from the last boot, and not one GCEInstanceSetup line. The other place the thumbprint can live, the guest attribute hostkeys/rdp, answered HTTP 412, "Constraint constraints/compute.disableGuestAttributesAccess violated". The VM presented its certificate over the tunnel without trouble (TLS 1.3, NLA), and neither the serial log nor the guest attributes gave me anything to compare it to. The serial API returns only the most recent 1 MB per port, and only from a running VM.

RDP over IAP is two jobs with different permissions

The data goes through a tunnel, and the password comes back by a route that never touches it:

gcloud compute start-iap-tunnel win-01 3389 \
    --local-host-port=localhost:13389 \
    --zone=europe-west1-b --project=acme-prod

gcloud compute reset-windows-password win-01 \
    --user=dana --zone=europe-west1-b --project=acme-prod

The RDP client then connects to localhost:13389. The tunnel needs an ingress rule from 35.235.240.0/20 to tcp:3389, and roles/iap.tunnelResourceAccessor for whoever connects (without the role it closes with 4033). The password command needs something else. Google's docs call it "write access to the Compute Engine project", which comes down to compute.instances.setMetadata and compute.instances.getSerialPortOutput, and IAP-secured Tunnel User has neither. Someone with only that role can open the tunnel and has no password to sign in with, so the reset has to come from whoever holds Compute Instance Admin on the VM.

How the Windows password reaches you

Google documents the steps for scripting it yourself, and IAP Desktop and my own client follow them:

The client makes a throwaway RSA-2048 key pair and keeps the private half in memory.
It adds an entry to the metadata key windows-keys with userName, email, the public key's modulus and exponent, and expireOn about five minutes ahead. It reads the current metadata first and writes it all back with the new entry, because the API's metadata update replaces the whole set.
The guest agent on the VM sees the entry, creates the account or resets its password, encrypts the password with that public key (RSA-OAEP) and prints a JSON line with encryptedPassword and the same modulus to serial port 4.
The client polls serial port 4, takes the line whose modulus matches its key, and decrypts.

Google's Go sample decrypts with OAEP over SHA-1. The entry can also carry hashFunction: "sha256", which the agent honours; my client asks for SHA-256 and falls back to SHA-1 for older agents.

Every reset replaces the previous password, so if a colleague ran reset-windows-password after you, your copy is dead and nothing tells you. The agent also needs a moment after it prints the line, and signing in straight away can fail once. My client polls port 4 thirty times, two seconds apart, before it gives up.

In an October test run my own client did that to me. Its Set Windows Password item reset admin whatever Windows user the VM was set to, and each run quietly killed the password I'd saved for that VM, so the next automatic sign-in failed until I saved it again.

What NLA does inside the IAP tunnel

Your RDP client connects to 127.0.0.1. IAP checks who you are and routes the stream to the VM you named, but it gives the client no proof that the far end is that VM. The name the client used, localhost, never matches the certificate subject, and Windows' RDP certificate is self-signed, so there's no CA to trust either. IAP Desktop connects without server authentication and so does my client. FreeRDP says so in its log: [DANGER] Certificate not checked.

CredSSP, the protocol behind NLA, is what ties your sign-in to the connection. During the exchange the client encrypts the server's TLS public key (from CredSSP version 5, a hash of it) into the authentication. A box in the middle that terminates TLS with its own key can't relay your sign-in to the real VM, because the key inside won't match.

A fake endpoint can still collect the NTLM response and crack it offline, and only a certificate check would catch that. A VM you sign in to also receives your delegated credentials, which Restricted Admin mode avoids by keeping the password off the VM.

If NLA is off and the server answers with TLS-only or standard RDP security, the password goes to the unchecked endpoint inside the Client Info PDU. From your machine to Google it still rides in the relay's TLS WebSocket, and from IAP to the VM it crosses Google's network to the internal address, so an attacker would need a position on that last stretch or an impostor VM with the same name. I keep NLA on and turn it off only for a VM I trust.

My client asks only for CredSSP (HYBRID_EX or HYBRID) and refuses a server that picks anything else, with no retry; a real Windows VM has always picked HYBRID when it was offered, and the log line after connect reads rdp security negotiated=HYBRID_EX nla=on. With NLA off on the client and required on the VM, FreeRDP stops with FREERDP_ERROR_CONNECT_HYBRID_REQUIRED_BY_SERVER.

With Restricted Admin mode on, my test Windows Server let NLA succeed, started the session, then showed "Account restrictions are preventing this user from signing in" and logged the session off. There was no connect error at all. If you see that message right after the desktop appears, turn Restricted Admin off and connect again.

Checking the RDP certificate thumbprint anyway

If you want Google's anchor, read it on the first boot, before anything restarts the VM:

gcloud compute instances get-serial-port-output win-01 --port=1 \
    --zone=europe-west1-b --project=acme-prod | grep "RDP certificate"

Google's instance_setup.ps1 writes that line once, from the first-boot setup script, and then deletes the script. The docs warn that the Thumbprint field "might be empty", and the script leaves it empty when it finds no certificate for CN=<hostname>. The Subject in the line is read from the WinRM certificate instead of the RDP one (a bug in the script), so compare only the thumbprint.

The same script puts the thumbprint into the guest attribute hostkeys/rdp too, which doesn't roll out of a buffer:

gcloud compute instances get-guest-attributes win-01 --query-path=hostkeys/ \
    --zone=europe-west1-b --project=acme-prod

It only writes it when the VM has enable-guest-attributes=TRUE in its metadata at first boot, so that has to be set at creation, and an org policy can block reading it, as it did above. I've seen this in the script source and not yet on a live VM, so test it on one VM before you rely on it. Reading either value needs compute.instances.getSerialPortOutput or compute.instances.getGuestAttributes, which Viewer, Compute Viewer and Compute Instance Admin have and IAP-secured Tunnel User doesn't. A mismatch can mean an attacker, or a certificate Windows has replaced since the first boot, and nothing tells you which.

The docs also give a way that doesn't depend on boot history: run PowerShell from the Special Administrative Console and read the certificate Windows holds right now.

Get-ChildItem 'Cert:\LocalMachine\Remote Desktop\' |
    Where-Object { $_.Subject -like "CN=$env:COMPUTERNAME*" -and $_.NotAfter -gt $(Get-Date) -and $_.HasPrivateKey } |
    Select-Object Subject, Thumbprint | Format-List

SAC sits on serial port 2 of the interactive serial console, which is off by default. You turn it on with the metadata key serial-port-enable=TRUE (that needs compute.instances.setMetadata), and opening a command channel in SAC asks for a Windows account. A different org policy blocks it, compute.disableSerialPortAccess, so an organization that blocks guest attributes may still allow this. It is the only one of the three that shows the current certificate rather than the one from the first boot.

Errors over the tunnel: 0x204, 4003 and 4010

Windows App on a Mac shows error code 0x204 when it can't reach a Remote Desktop server at the address you gave it. Over IAP that's the path: the VM still booting, the firewall rule, the tunnel role, or a client pointed at a port where no start-iap-tunnel is listening.

A missing firewall rule fails slowly. When I measured it, IAP took about 31 seconds to close a connection to a port with no rule with 4003, while an open port answered in about 1.1 seconds. IAP Desktop's default connect timeout is 30 seconds. A client that gives up first reports its own timeout, and you never see the 4003 that would have pointed at the firewall. If RDP hangs for half a minute and then fails, check the 3389 rule before you reset anyone's password.

RDP sessions in my client died whenever I scrolled fast, with close code 4010. The pump that copied the local socket into the relay sent frames concurrently, and a burst of scroll input could reorder them. The VM got a TLS stream with bytes out of order, answered with a TCP reset, and IAP closed the session. Reading the socket, waiting for the send to finish, and only then reading again fixed it.

I build Ostgate, a paid macOS app that does the password and RDP steps above without gcloud, and it leaves the certificate unchecked for the reasons above. It isn't affiliated with Google: https://ostgate.app

What gcloud start-iap-tunnel is doing while your SSH session hangs

Edgar — Fri, 30 Oct 2026 10:03:04 +0000

Originally published in Google Cloud - Community.

I switched Wi-Fi off and on while testing the Mac client I'm building, and an IAP tunnel to a healthy VM took almost three minutes to come back.

I manage VMs in more than ten Google Cloud organizations from a Mac, and for a long time that meant playing gcloud like a piano: an alias per project, a couple of bash scripts to switch accounts, and an export CLOUDSDK_BILLING_QUOTA_PROJECT=... because the quota project kept pointing at some other organization. The scripts didn't always switch everything, so now and then I ran a perfectly good command in the wrong organization. And when I closed the laptop or moved to another network, the SSH session froze and I never knew whether to wait or kill the tunnel.

Google doesn't publish the protocol behind IAP TCP forwarding. The closest thing to a spec is the source of the two clients that use it, gcloud (Python) and IAP Desktop (C#).

One WebSocket per connection

gcloud compute start-iap-tunnel example-vm 22 --local-host-port=localhost:2222 --zone=europe-west1-b

This only opens port 2222 on your Mac. When ssh connects to it, gcloud opens a WebSocket to tunnel.cloudproxy.app, and IAP opens a plain TCP connection to port 22 of the VM from an address in 35.235.240.0/20, so the VM never sees your IP. Open three terminals through that one port and you get three WebSockets and three connections to the VM.

Your Google access token rides along as an ordinary bearer header. If it's the wrong token, or the account lacks roles/iap.tunnelResourceAccessor, the WebSocket still opens and only then closes with code 4033, after ssh has already connected to port 2222.

Inside the WebSocket

Every message is a binary frame with a two-byte type:

1   CONNECT_SUCCESS_SID     session ID, kept for reconnects
2   RECONNECT_SUCCESS_ACK   bytes the server had when the old socket died
4   DATA                    up to 16,384 bytes of your stream
7   ACK                     running total of bytes received
10  LONG_CLOSE              close code and reason

The sender keeps every DATA frame until the other side's ACK total passes it. gcloud sends a standalone ACK once it owes 32 KiB, IAP Desktop once it owes 1 MiB. Up to that much can sit queued for a resend.

When the network drops

If the WebSocket drops without a close frame, the client reconnects to the same session. It calls /v4/reconnect with the session ID and the number of bytes it has received. The server replies with its own count, the client resends what's missing, and the TCP connection to the VM carries on.

gcloud retries for up to fifteen minutes, starting 1.5 seconds apart and backing off to 20 seconds, and gives each attempt up to a minute to open. IAP Desktop stops after two reconnects.

In my Wi-Fi test the relay refused one reconnect with 4077, "Failed to takeover the existing session", then left the next two open for a minute each without any reply. A client can recover sooner by giving up on the reconnect and opening a fresh session, but that costs the SSH session: a new relay session is a new TCP connection to port 22. For a tunnel that carries a database forward, I'd rather drop it and reopen in seconds than stare at a frozen terminal for three minutes. An interactive shell is the one case where I'd still wait. My client does the same: a bastion forward drops a stalled reconnect and opens a fresh session, an SSH tab keeps retrying and redials when macOS says the network is back.

What 4033, 4003 and 4047 mean

4033: IAP won't let you in. With ten organizations on one laptop, for me this was almost always a correct command under the wrong account, so I run gcloud config list account before I open the IAM page.
4003: IAP reached your network but not the port. Usually a missing firewall rule for 35.235.240.0/20, or nothing listens on the VM.
4047: wrong instance, zone or project.
1006 and most others: a dropped connection. Reconnect.

I build Ostgate, a paid macOS app that talks to this relay directly for SSH, SFTP, RDP and tunnels without gcloud. It isn't affiliated with Google: https://ostgate.app