Connecting to instances using advanced methods

If you need to manage your own credentials, use third-party tools, or connect to an instance by using alternative connection paths, the following advanced methods might fit your needs better than the standard methods described in Connecting to instances.

There are several advanced methods to connect to Linux and Windows Server instances:

• Linux instances:
  • Connect to instances using third-party tools
  • Connect to instances that don't have external IP addresses
  • Connect to instances as the root user
• Windows Server instances:
  • Connect to Windows instances using the PowerShell terminal

Before you begin

• If you want to use the command-line examples in this guide:
  1. Install or update to the latest version of the gcloud command-line tool.
  2. Set a default region and zone.

Providing public SSH keys to instances

Normally, Compute Engine creates and manages SSH keys for you whenever you connect using the methods described in Connecting to instances.

However, if you need to use your own SSH keys (for example, when using third-party tools to connect), you must generate your own SSH key pair and provide your public SSH key file to the instance before you can connect.

If you're not familiar with how to generate your own SSH key pair and how to locate your public SSH key file, see Creating a new SSH key and Locating an SSH key.

To provide your SSH key to the instance, use one of the following methods:

• (Recommended) Enable OS Login and use IAM roles to provide your public SSH key to the instance through your Google Account or a managed user account. To do so, follow the steps in Managing instance access using OS Login to enable OS Login and create the roles. Then, see the Adding SSH keys to a user account section to add your public key to the role you want to use to connect to your instance.

  Note: With OS Login, you don't have to create and manage individual SSH keys because it manages SSH access to your instances using Cloud Identity and Access Management. OS Login also lets you maintain a consistent Linux user identity across VM instances.

• (Not recommended) Manually add and remove SSH keys by editing project or instance metadata. See Managing SSH keys in metadata. This method adds unnecessary risks and complexity and is not recommended unless the OS Login method above doesn't work for you. For more information, see Risks of manual key management.

• If your instance is managed by someone else who already has access (such as a Systems Administrator in your organization), you can also provide your public SSH key file to them and ask them to manually configure it for you. Usually, this involves them connecting to your instance, copying your public key file into your home directory on your instance, and changing the permissions on the file, but this will depend on how your organization manages your instances.

Connecting using third-party tools

After providing your public SSH key to the instance, you can use third-party SSH tools along with your matching private SSH key to connect.

To connect, click the tab for your local operating system and follow the steps:

Linux & macOS

To connect using SSH from a Linux or macOS machine, use the built-in ssh command in a local terminal.

1. If you haven't done so already, provide your public SSH key to an instance using one of the available options. You won't be able to proceed without this.

2. In the console, go to the instances page (or click the button below) and find the external IP address for the instance you want to connect to.

   Go to the Instances page

3. In a local terminal, use the ssh command along with your private SSH key file, the username associated with the SSH key, and the external IP address of the instance to connect. For example:

   ssh -i [PATH_TO_PRIVATE_KEY] [USERNAME]@[EXTERNAL_IP_ADDRESS]

   where:

   • [PATH_TO_PRIVATE_KEY] is the path to your private SSH key file.
   • [USERNAME] is the username of the user connecting to the instance. If you manually created your SSH keys, this must be the username you specified when you created the SSH key.
   • [EXTERNAL_IP_ADDRESS] is the external IP address for your instance.

   After connecting, run commands on your instance using this terminal. When you have finished using the instance, disconnect from it by using the exit command.

Windows (PuTTY)

Windows doesn't include a built-in SSH client, which means you must download and install a third-party client. The following instructions show how to connect using PuTTY.

To connect to an instance from Windows using PuTTY, do the following:

1. If you haven't done so already, provide your public SSH key to an instance using one of the available options. You won't be able to proceed without this.

2. In the console, go to the instances page (or click the button below) and find the external IP address for the instance that you want to connect to. Keep it available for later steps.

   Go to the Instances page

3. Download putty.exe, if you haven't done so already.

4. Open PuTTY by launching putty.exe. A connection configuration window opens.

5. In the Host Name field in the connection configuration page, enter the username associated with the SSH key and the external IP address of the instance that you want to connect to in the following format:

   [USERNAME]@[EXTERNAL_IP_ADDRESS]

   where:

   • [USERNAME] is the username of the user connecting to the instance. This must be the username you specified when you created the SSH key.

   • [EXTERNAL_IP_ADDRESS] is the external IP address of the instance that you want to connect to.

     For example, see the following screenshot:

     

6. In the Category menu on the left, navigate to Connection > SSH > Auth.

7. In the Private key file for authentication field, browse to the location of your private key file.

   For example, see the following screenshot:

   

8. Click Open to open a terminal with a connection to your instance.

   After connecting, run commands on your instance using this terminal. When you have finished using the instance, disconnect from it by using the exit command.

Chrome (SSH app)

Chromebooks or operating systems with Chrome installed use Secure Shell app as an SSH client. To connect to instances from the Secure Shell app, do the following steps:

1. If you haven't done so already, provide your public SSH key to an instance using one of the available options. You won't be able to proceed without this.

2. Install the Secure Shell app on your Chromebook or the Chrome browser if you haven't done so already.

3. In the console, go to the instances page (or click the button below) and find the external IP address for the instance that you want to connect to. Keep it available for later steps.

   Go to the Instances page

4. Open the Secure Shell app in a Chrome browser tab.

5. Enter the username associated with the SSH key pair and the external IP address for the instance that you want to connect to in the following format:

   [USERNAME]@[EXTERNAL_IP_ADDRESS]

   where:

   • [USERNAME] is the username of the user connecting to the instance. This must be the username you specified when you created the SSH key.
   • [EXTERNAL_IP_ADDRESS] is the external IP address of the instance that you want to connect to.

6. In the Identity field, select the private SSH key file that you want to use to connect to the instance. If necessary, click Import to select a private key file from your local workstation.

7. Click Connect to connect to the instance.

   After connecting, run commands on your instance using this terminal. When you have finished using the instance, disconnect from it by using the exit command.

Other SSH options

In addition to the options detailed above, other options for connecting to an instance using SSH include:

• SSH from the browser.
• The gcloud compute ssh command. For more information, see the gcloud compute ssh reference documentation.

Connecting to an instance that doesn't have an external IP address

If you have an isolated instance that doesn't have an external IP address (such as an instance that is intentionally isolated from external networks), you can still connect to it by using its internal IP address on a Google Cloud Platform Virtual Private Cloud (VPC) network using the following methods.

Important: The following methods only work if your GCP VPC network has one or more firewall rules that allow SSH connections on port 22. The firewall rules must allow SSH connections for the IP ranges or specific IP addresses from which you want to connect.

• Connect to instances over a VPN connection that has access to the internal IP addresses of instances on your GCP VPC.
• Connect through a bastion host instance to gain access to the internal IP address on your GCP VPC. Then, connect from the bastion host to other instances on the same internal VPC network or instances on a peered VPC network.
• Connect using Cloud Identity-Aware Proxy for TCP forwarding to forward an SSH connection to a remote instance.

Connecting over a VPN

To use a Virtual Private Network (VPN) to connect to an instance without an external IP address, you must have a computer that's already connected to the same VPN as the instance you want to reach. For example, you might have a VPN that your local on-premises network shares with your GCP VPC. If so, connect to the instance using the gcloud command-line tool, SSH on Linux and macOS, or third-party SSH clients such as PuTTY on Windows.

For more information, see the following tabs:

gcloud

Connect to an instance without an external IP address by using the gcloud compute ssh command with the --internal-ip flag.

gcloud compute ssh [INTERNAL_INSTANCE_NAME] --internal-ip

Where [INTERNAL_INSTANCE_NAME] is the name of the instance that you want to connect to.

After connecting, run commands on your instance using this terminal. When you have finished using the instance, disconnect from it by using the exit command.

Linux & macOS

To connect to an instance without an external IP address from a Linux or macOS workstation, do the following:

1. Provide your public SSH key to an instance using one of the available options. You won't be able to proceed without this.

2. On your local machine, start the ssh-agent to manage your SSH keys for you:

   $ eval ssh-agent $SHELL
   

3. Use the ssh-add command to load your private SSH key from your local computer into the agent and use your private SSH key for authentication of all SSH commands.

   $ ssh-add ~/.ssh/[PRIVATE_KEY]
   

   where [PRIVATE_KEY] is the filename of your private key file.

4. In the console, go to the instances page (or click the button below) and find the internal IP address of the instance that you want to connect to.

   [Go to the Instances page](https://console.cloud.google.com/compute/instances){: class="button button-primary" target="console" track-type="tasks" track-name="consoleLink" track-metadata-position="body" track-metadata-end-goal="attachDisk"}

   1. In a local terminal, use the ssh command along with the username associated with your private SSH key, and the internal IP address of the instance to connect to. For example:

   $ ssh [USERNAME]@[INTERNAL_INSTANCE_IP_ADDRESS]

   where:

   • [USERNAME] is the username of the user connecting to the instance. This must be the username you specified when you created the SSH key.
   • [INTERNAL_INSTANCE_IP_ADDRESS] is the internal IP address of the instance that you want to connect to.

   After connecting, run commands on your instance using this terminal. When you have finished using the instance, disconnect from it by using the exit command.

Windows (PuTTY)

To connect to an instance without an external IP address from a Windows workstation:

1. If you haven't done so already, provide your public SSH key to an instance using one of the available options. You won't be able to proceed without this.

2. In the console, go to the instances page (or click the button below) and find the internal IP address of the instance that you want to connect to.

   Go to the Instances page

3. Connect to an instance using PuTTY from Windows except specify the internal address of the instance you want to connect to instead of specifying an external IP address.

   After connecting, run commands on your instance using this terminal. When you have finished using the instance, disconnect from it by using the exit command.

Connecting through a bastion host

Another method of connecting to an instance that doesn't have an external IP address is to connect through a bastion host. Using a bastion host also lets you to connect to instances on other peered VPC networks.

To connect to an instance through a bastion host from Linux and macOS, use either the gcloud command-line tool or SSH. To connect from Windows, use a third-party SSH client such as PuTTY.

As with the other methods, connecting to other instances from a bastion host requires a private SSH key. There are several ways to manage this:

• Install the gcloud command-line tool and configure it to manage your private keys for you.
• Forward your private key to the bastion host instance by enabling agent forwarding in your SSH client.

Note: The following examples assume that you're using a bastion host that is running on the Linux operating system. To follow along, confirm that the bastion host you're using is running on Linux.

gcloud

Beta

This is a Beta release of SSH to internal IP addresses using the gcloud command-line tool. This feature is not covered by any SLA or deprecation policy and might be subject to backward-incompatible changes.

The gcloud command-line tool allows you to connect to instances that don't have external IP addresses without forwarding your private SSH keys to the bastion host. To do this, install gcloud on both your local workstation and the bastion host instance, if you haven't done so already.

Note: If you have circumstances that require forwarding your private keys instead of allowing the gcloud tool to manage them for you, see the Linux or macOS or Windows tab and look for the steps about using ssh-agent to forward your key. Follow that step, then return to step 3 below and use gcloud compute ssh to connect.

To use the gcloud command-line tool to connect to an instance that doesn't have an external IP address:

1. Set a read/write Compute Engine API access scope for the service account on your bastion host instance by including --scopes compute-rw in your command. For more information, see Changing the service account and access scopes for an instance.

2. Grant the necessary IAM permissions to allow your bastion host to access your public SSH key by using either OS Login (recommended) or project meta data.

   • OS Login (recommended):

     1. Enable OS Login.

     2. Grant the necessary IAM permissions to access your instances with OS Login.

   • Project metadata:

     1. Grant the necessary IAM permissions for your instances to edit metadata.

        (Tip: you can add the Compute Engine Instance Admin role to your service account.)

   The service account on your bastion host should now be able to apply your public SSH key.

3. Connect to the Linux bastion host instance:

   gcloud compute ssh [EXTERNAL_INSTANCE_NAME]
   

   where [EXTERNAL_INSTANCE_NAME] is the name of the bastion host instance that you're using to gain access to the internal network.

4. From the Linux bastion host instance, use the gcloud compute ssh command with the --internal-ip flag to connect to instances using their internal IP addresses:

   gcloud compute ssh [INTERNAL_INSTANCE_NAME] --internal-ip
   

   where [INTERNAL_INSTANCE_NAME] is the name of the instance that you want to connect to.

After connecting, run commands on your instance using this terminal. When you have finished using the instance, disconnect from it by using the exit command.

Linux & macOS

If you need to forward private keys to the bastion host instance, you must add your keys to the ssh-agent. Then, use either the gcloud compute ssh command or the ssh command to establish the initial connection to the bastion host and forward the keys in the SSH agent. This process works only on Linux and macOS workstations. If you need to forward private keys to a bastion host from a Windows workstation, follow the PuTTY instructions instead.

To connect to an instance without an external IP address from Linux or macOS workstations:

1. Provide your public SSH key using one of the available options. Make sure you provide this public SSH key to both the Linux bastion host instance and the instance without an external IP address.

2. On your local machine, start the ssh-agent to manage your SSH keys for you:

   $ eval ssh-agent $SHELL
   

3. Use the ssh-add command to load your private SSH key from your local computer into the agent and use your private SSH key for authentication of all SSH commands.

   $ ssh-add ~/.ssh/[PRIVATE_KEY]
   

   where [PRIVATE_KEY] is the filename of your private key file.

4. Find the external IP address of the Linux bastion host instance, and find the internal IP address of the internal instance that you want to connect to. You can find the addresses in the External IP and Internal IP columns on your Instances page.

   Go to the Instances page

5. Connect to the Linux bastion host instance using either ssh or gcloud compute ssh. For either option, include the -A argument to enable authentication agent forwarding.

   Connect to the Linux bastion host instance and forward your private keys with ssh.

   $ ssh -A [USERNAME]@[BASTION_HOST_EXTERNAL_IP_ADDRESS]

   where:

   • [USERNAME] is the name attached to your SSH key.
   • [BASTION_HOST_EXTERNAL_IP_ADDRESS] is the external IP address of the bastion host instance that you're using to gain access to the internal network.

   Alternatively, you can connect to the bastion host instance and forward your private keys using the gcloud compute ssh command. This option allows you to connect to the bastion host instance using the gcloud command-line tool and then use regular ssh with the forwarded credentials when you connect to internal IP addresses.

   gcloud compute ssh --ssh-flag="-A" [BASTION_HOST_INSTANCE_NAME]
   

   where [BASTION_HOST_INSTANCE_NAME] is the name of the bastion host instance that you're using to gain access to your internal network.

6. From the Linux bastion host instance, connect to the instance that doesn't have an external IP address by using SSH.

   $ ssh [USERNAME]@[INTERNAL_INSTANCE_IP_ADDRESS]

   where:

   • [USERNAME] is the name attached to your SSH key.
   • [INTERNAL_INSTANCE_IP_ADDRESS] is the internal IP address of the instance that you want to connect to.

After connecting, run commands on your instance using this terminal. When you have finished using the instance, disconnect from it by using the exit command.

Windows (PuTTY)

To connect to an instance without an external IP address from Windows workstations:

1. Provide your public SSH key using one of the available options. Make sure you provide this public SSH key to both the Linux bastion host instance and the instance without an external IP address.

2. Find the external IP address of the Linux bastion host instance, and find the internal IP address of the internal instance that you want to connect to. You can find the addresses in the External IP and Internal IP columns on your Instances page.

   Go to the Instances page

3. Connect to the Linux bastion host instance by using PuTTY. To pass your private SSH key to the bastion host, enable the Allow agent forwarding setting, as shown in the following screenshot:

   

4. Connect from the Linux bastion host instance to the instance that doesn't have an external IP address by using SSH:

   $ ssh [USERNAME]@[INTERNAL_IP_ADDRESS]
   

   where:

   • [USERNAME] is the username of the user connecting to the instance. This must be the username you specified when you created the SSH key.
   • [INTERNAL_IP_ADDRESS] is the internal IP address of the instance that you want to connect to.

   After connecting, run commands on your instance using this terminal. When you have finished using the instance, disconnect from it by using the exit command.

Connecting through Cloud IAP

Using SSH with Cloud IAP's TCP forwarding feature wraps an SSH connection inside HTTPS. Cloud IAP's TCP forwarding feature then sends it to the remote instance.

To learn how to connect to a remote instance with Cloud IAP, see Using Cloud IAP for TCP forwarding.

Connecting to an instance as the root user

By default, public images and most common operating systems don't allow root login using SSH. Instances allow you to connect as root using SSH only if you configure them to operate that way.

As a best practice, the /etc/ssh/sshd_config SSH configuration file has the PermitRootLogin parameter set to no. Because of this parameter setting, you can't connect to an instance as the root user even if you specify an SSH key for root in your project or instance metadata. If a user requires root permissions, they can get those permissions by running commands through sudo.

If you configured an instance to allow SSH as the root user and configure an SSH key for the root user on that instance, you can connect as root using the gcloud compute ssh command with root@ specified before the instance name:

gcloud compute ssh --project [PROJECT_ID] --zone [ZONE] root@[INSTANCE_NAME]

where:

• [PROJECT_ID] is the ID of the project that contains the instance.
• [ZONE] is the name of the zone in which the instance is located.
• [INSTANCE_NAME] is the name of the instance.

Connecting to a Windows instance using PowerShell

If you have a Windows workstation with PowerShell, you can connect to a Windows Server instance through a remote PowerShell session. This process is similar to connecting to a Linux instance using SSH.

1. If you haven't created a username and password on the remote Windows instance yet, create or reset your Windows password.

2. Add a firewall rule that opens port 5986 on the GCP VPC network where your Windows Server instance is located.

3. On your local workstation, open the PowerShell terminal.

4. Optionally, you can initialize a variable to hold your user credentials so you don't need to enter them each time you connect to the instance. If you skip this step, you receive a prompt for your username and password later.

   PS C:\> $credentials = Get-Credential
   

5. Use the Enter-PSSession command to start a remote PowerShell session and include the flags to use SSL and skip credentials checks.

   PS C:\> Enter-PSSession -ComputerName [IP_ADDRESS] -UseSSL -SessionOption (New-PSSessionOption -SkipCACheck -SkipCNCheck) -Credential $credentials
   

   where [IP_ADDRESS] is the external IP address, DNS name, or Windows computer name for the instance to which you want to connect.

   Note: To find the external IP address of your Windows instance, either go to the instances page (or click the button below) or run gcloud compute instances list in the gcloud command-line tool.

   Go to the Instances page

After connecting, the command prompt changes to include the IP address of the remote Windows instance. You can now use the terminal to run PowerShell commands on the remote Windows Server instance.

As an alternative to the Enter-PSSession command, you can run Invoke-Command with the -ScriptBlock flag to execute PowerShell commands on the remote instance without establishing an interactive session.

PS C:\> Invoke-Command -ComputerName [IP_ADDRESS] -ScriptBlock { [SCRIPT] } -UseSSL -SessionOption (New-PSSessionOption -SkipCACheck -SkipCNCheck) -Credential $credentials

where:

• [IP_ADDRESS] is the IP address, DNS name, or Windows computer name for the instance to which you want to connect.
• [SCRIPT] is one or more commands to run on the remote instance. For example, specify Get-EventLog -log "Windows PowerShell" to get a list of log events.

Manually connecting between instances as a service account

In some situations, you might want to connect to instances and run commands as if you were the service account associated with that instance. The gcloud compute ssh command lets you use the SSH credentials of a service account to connect from one instance to another, allowing you to run commands on the second instance as the service account.

The gcloud command-line tool automatically generates an SSH key pair and associates it with the service account on your instance. After you connect to another instance as the service account, you can run additional gcloud commands using the service account's IAM permissions.

For this example, assume that you have the following environment:

• Instance A:
  • Instance A has a service account associated with it.
  • The service account associated with Instance A has the necessary OS Login roles configured either at the project level or specifically for the Instance B resource.
  • The service account has the https://www.googleapis.com/auth/cloud-platform platform-wide scope on Instance A.
• Instance B:
  • Instance B runs either on the same internal network as Instance A or on a network with firewall rules that allow SSH connections from Instance A.
  • The OS Login feature is enabled on your project or specifically on Instance B.
• Your personal user account:
  • Your account has the roles/iam.serviceAccountUser role for the service account associated with Instance A.
  • Your account has SSH access specifically to Instance A.
  • Your account has no access to Instance B. The service account is the only account with the OS Login roles that are necessary for connecting to Instance B.

Connect to Instance A and execute commands as that service account. This step requires that you have the roles/iam.serviceAccountUser role for that service account:

1. Connect to Instance A as the user with the roles/iam.serviceAccountUser role. For example, you can use the gcloud command-line tool to establish this first SSH connection:

   my-username@localworkstation:~$ gcloud compute ssh instance-a --project my-project --zone us-east1-d
   

2. After you SSH to Instance A, you can execute commands as if you were the service account as long as you have the roles/iam.serviceAccountUser role. In this example, run the gcloud command-line tool on Instance A to create a chain-SSH connection to Instance B. The gcloud command-line tool identifies that Instance B is enabled to use OS Login and also identifies that the service account has the necessary IAM roles for establishing an SSH connection to Instance B.

   my-username@instance-a:~$ gcloud compute ssh instance-b --project my-project --zone us-east1-d
   
   WARNING: Using OS Login user [sa_113491385848438711199] instead of default user [my-username]
   Linux instance-b 4.9.0-8-amd64 #1 SMP Debian 4.9.110-3+deb9u6 (2018-10-08) x86_64
   ⋮
   
   

3. You are now connected to Instance B as the service account, and can execute commands as that service account.

   sa_113491385848438711199@instance-b:~$ uname -a
   
   Linux instance-b 4.9.0-8-amd64 #1 SMP Debian 4.9.110-3+deb9u6 (2018-10-08) x86_64 GNU/Linux
   
   

What's next

• Learn how to manage access to instances for multiple users across a project or organization.
• Securely connect to VM instances.
• Transfer files to your Linux instances.