Connect to Linux VMs using Identity-Aware Proxy
This document describes how to connect to a virtual machine (VM) instancethrough its internal IP address, usingIdentity-Aware Proxy (IAP) TCP forwarding.
IAP TCP forwarding lets you establish an encrypted tunnelover which you can forward SSH connections to VMs. When you connect to a VMthat uses IAP, IAP wraps the SSH connectioninside HTTPS before forwarding the connection to the VM. Then,IAP checks if you have therequired IAM permissionsand if you do, grants access to the VM.
If you need to connect to a VM that doesn't have external IP addresses and youcan't use IAP, review the other methods listed inConnection options for internal-only VMs.
Before you begin
- Create a firewall ruleto enable connections from IAP.
- If you haven't already, set upauthentication. Authentication verifies your identity for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:
Select the tab for how you plan to use the samples on this page:
Console
When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:
gcloudinit
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.- Set a default region and zone.
Supported operating systems
These connection methods are supported for allpublic Linux images that are available onCompute Engine. For Fedora CoreOS images, you mustset up SSH access before you can use these methods.
Connect to VMs
To connect to a VM, complete the steps in one of the following tabs.
Permissions required for this task
To perform this task, you must have the followingpermissions:
- All permissions included in theIAP roles.
Console
Tunnel SSH connections through a VM's internal IP address usingSSH-in-Browser by doing the following:
Note: SSH-in-Browser only uses IAP if the VM doesn't havean external IP address.- In the Google Cloud console, go to theVM instances page.
- In the list of virtual machine instances, clickSSH in the row of the instance that you want to connect to.
gcloud
Tunnel SSH connections through a VM's internal IP address using thegcloud compute ssh command with the--tunnel-through-iap flag:
Connect to the VM by running the following command:
gcloud compute sshVM-NAME \ --tunnel-through-iap
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, aCloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
ReplaceVM_NAME with the name of the VM that you want to connect to.
IAP Desktop
To connect to a VM using IAP Desktop, do the following:
Install IAP Desktop on your workstation if you haven't already.
Open IAP Desktop. TheAdd projects window opens.
When prompted, sign in using the Google account that has access to the project with the VMs you want to connect to.
In theAdd projects window, enter the project ID or name of the project that contains the VMs you want to connect to.
In theProject Explorer window, right-click the name of the VM again and selectConnect to connect to the VM.
PuTTY app
Tunnel SSH connections through a VM's internal IP address using PuTTY, by doing the following:
- Add an SSH key to the VM if you haven't already.
- If your workstation doesn't already have the PuTTY app installed,download the PuTTY package files.
In the Google Cloud console, go to theVM Instances page and find the name of the VM that you want to connect to.
- Open the PuTTY app. A connection configuration window opens.
In the
Host Namefield, enter the username associated with the SSH key, and the name of the VM that you want to connect to. Use the following format:USERNAME@VM_NAME
Replace the following:
USERNAME: your username. If you manage your SSH keys in metadata, the username is what you specified when youcreated the SSH key. For OS Login accounts, the username isdefined in your Google profile. For example,cloudysanfrancisco_example_comorcloudysanfrancisco.NAME: the name of the VM.
- In theCategory menu, navigate toConnection > SSH > Auth.
- In thePrivate key file for authentication field, select the private SSH key file that corresponds to the public key you added to the VM.
- In theCategory menu, navigate toConnection > Proxy.
- In theProxy type section, selectLocal.
In theTelnet command, or local proxy command field, enter the following command:
gcloud.cmd compute start-iap-tunnelVM_NAMEPORT_NUMBER --listen-on-stdin --project=PROJECT_ID --zone=ZONE
Replace the following:
VM_NAME: the name of the VM that you want to connect to.PORT_NUMBER: the port that the sshd daemon runs on. The defaultPORT_NUMBERis22.PROJECT_ID: the project that hosts the VM that you want to connect to.ZONE: the zone where the VM is located.
- ClickOpen to connect to the VM.
Troubleshooting
To find methods for diagnosing and resolving failed SSH connections, seeTroubleshooting SSH.
What's next
- Learn how tomanage access to VMs.
- Learn how totransfer files to VMs.
- Learn howSSH connections to Linux VMswork on Compute Engine.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-12-15 UTC.