onboard-new-vm

name	onboard-new-vm
description	Use when the user wants to add one or more new GCE VMs as saved connections in IAP Tunnel Manager — including resolving project + zone + platform from natural language and choosing a sensible local port. Triggers on "add a new VM", "save these instances", "bookmark these for IAP".

Onboard new GCE VMs as saved connections

When the user names VMs by string

1. auth_check → auth_login if needed.
2. projects_list { filter } to locate the project. If multiple match, ask the user to pick.
3. For each VM: vms_list { projectId, filter: <vmName> }. Confirm name, zone, isWindows.
4. connections_list → skip any VM that already has a saved connection (compare projectId + instanceName + zone).
5. For each new VM, call:

   connections_add {
     displayName: "<short, recognisable label>",
     projectId, projectName,
     instanceName, zone,
     platform: isWindows ? "windows" : "linux",
     remotePort: isWindows ? 3389 : 22,
     username: <ask if not provided>,
     preferredLocalPort: 0       // 0 = auto-allocate
   }
   

6. Summarise: created N connections, allocated ports […], skipped K duplicates.

When the user wants "all dev VMs in "

1. vms_list { projectId, filter } (filter on a label-style substring like dev-).
2. Show the result and ask the user to confirm the set before bulk-adding.
3. Bulk connections_add with the same logic above.

Pitfalls

• Port collisions: auto-allocation handles new connections, but if the user asks for specific local ports, validate against connections_list first.
• OS login: for Linux VMs that require OS Login, ssh_install_key won't help — note this when adding.
• Don't tunnels_start_for_connection for every newly-added VM unless the user asks; starting tunnels has resource cost and is unnecessary for "just save them".