Connecting to instances using advanced methods

In general, the best SSH connection methods are described on the Connecting to instances page. However, in cases where you need to manage your own credentials, use third-party tools, or connect using alternative connection paths, the following advanced methods might fit your needs better than the standard methods.

There are several advanced methods that you can use to connect to Linux and Windows Server instances:

• Linux instances:
  • Connect to instances using third-party tools
  • Connect to instances that do not 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.
• If you want to use the API examples in this guide, set up API access.

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 are not familiar with how to generate your own SSH key 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 Setting up 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: OS Login lets you maintain a consistent Linux user identity across VM instances, and manages SSH access to your instances using IAM without having to create and manage individual SSH keys. This simplifies the process for managing SSH keys for most users.

• (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 does not work for you. 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 depends 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, follow the steps for the operating system on your local workstation:

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 have not done so already, provide your public SSH key to an instance using one of the available options. You cannot proceed without this.

2. In the Google Cloud Console, go to the VM instances page and find the external IP address for the instance that 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, and the external IP address of the instance to connect. For example:

   ssh -i path-to-private-key username@external-ip

   Replace the following:

   • path-to-private-key: The path to your private SSH key file.
   • username: The username of the user connecting to the instance. For OS Login accounts, the username is defined in your user profile. If you manage your SSH keys in metadata, the username is what you specified when you created the SSH key.
   • external-ip: The external IP address for your instance.

   After you connect, run commands on your instance using this terminal. When you finish, disconnect from the instance by running the exit command.

Windows (PuTTY)

Windows does not 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 have not done so already, provide your public SSH key to an instance using one of the available options. You cannot proceed without this.

2. In the Google Cloud Console, go to the VM instances page and find the external IP address for the instance that you want to connect to. Keep the external IP address available for later steps.

   Go to the Instances page

3. Download putty.exe, if you have not 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

   Replace the following:

   • username: The username of the user connecting to the instance. This must be the username you specified when you created the SSH key.

   • external-ip: 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 you connect, run commands on your instance using this terminal. When you finish, disconnect from the instance by running the exit command.

Chrome OS (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:

1. If you have not done so already, provide your public SSH key to an instance using one of the available options. You cannot proceed without this.

2. Install the Secure Shell app on your Chromebook or the Chrome browser if you have not done so already.

3. In the Google Cloud Console, go to the VM instances page and find the external IP address for the instance that you want to connect to. Keep the external IP address 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

   Replace the following:

   • username: The username of the user who is connecting to the instance. This must be the username you specified when you created the SSH key.
   • external-ip: 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 you connect, run commands on your instance using this terminal. When you finish, disconnect from the instance by running 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.
• gcloud compute ssh command. See the gcloud compute ssh reference documentation for details.

Connecting to instances that do not have external IP addresses

If you have isolated instances that do not have an external IP address you can still connect to those instances using their internal IP addresses on a Google Cloud VPC network. For example, you can still connect to VM instances that you intentionally isolate from external networks by using the following methods:

• Connect to instances over a VPN connection that has access to the internal IP addresses of instances on your Google Cloud 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 Identity-Aware Proxy for TCP forwarding to forward an SSH connection to a remote instance.

Important: For these methods to work, your VPC network must have 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.

Connecting over a VPN connection

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 Google Cloud VPC. In that situation, 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.

See the following tabs for details:

gcloud

Connect to an instance without an external IP address by using the gcloud compute ssh command with the --internal-ip flag. Replace internal-instance-name with the name of the instance that you want to connect to.

gcloud compute ssh internal-instance-name --internal-ip

After you connect, run commands on your instance using this terminal. When you finish, disconnect from the instance by running the exit command.

Linux & macOS

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

1. Provide your public SSH key to an instance using one of the available options. You cannot 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. Replace private-key with the filename of your private key file.

   $ ssh-add ~/.ssh/private-key
   

4. In the Google Cloud Console, go to the VM instances page and find the internal IP address for 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"}

5. 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

   Replace the following:

   • username: The username of the user who is connecting to the instance. This must be the username you specified when you created the SSH key.
   • internal-instance-ip-address: The internal IP address of the instance that you want to connect to.

After you connect, run commands on your instance using this terminal. When you finish, disconnect from the instance by running the exit command.

Windows (PuTTY)

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

1. If you have not done so already, provide your public SSH key to an instance using one of the available options. You cannot proceed without this.

2. In the Google Cloud Console, go to the VM instances page and find the internal IP address for the instance that you want to connect to.

   Go to the Instances page

3. Follow the steps above to connect to an instance using Putty from Windows, but make the following change:

   • Where the steps instruct you to specify an external IP address, instead specify the internal address of the instance you want to connect to.

After you connect, run commands on your instance using this terminal. When you finish, disconnect from the instance by running the exit command.

Connecting through a bastion host

Another method of connecting to an instance that does not have an external IP address is to connect through a bastion host. Using a bastion host also lets you 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.

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 examples below assume that you are using a bastion host with a Linux operating system. If you want to follow along, confirm that the bastion host you are using is running Linux.

See the examples below for complete steps:

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 lets you connect to instances that do not 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 have not 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 tabs and look for the steps about using ssh-agent to forward your key. After you use ssh-agent to forward your key, return to this procedure and use gcloud compute ssh to connect.

To use the gcloud command-line tool to connect to an instance that does not 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 either using OS Login (recommended) or project metadata. Use one of the following procedures:

   • 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 can now apply your public SSH key.

3. Connect to the Linux bastion host instance. Replace external-instance-name with the name of the bastion host instance that you're using to gain access to the internal network.

   gcloud compute ssh external-instance-name
   

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. Replace internal-instance-name with the name of the instance that you want to connect to.

   gcloud compute ssh internal-instance-name --internal-ip
   

After you connect, run commands on your instance using this terminal. When you finish, disconnect from the instance by running 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 it for authentication of all SSH commands. Replace private-key with the filename of your private key file.

   $ ssh-add ~/.ssh/private-key
   

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 VM 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

   Replace the following:

   • username: The name attached to your SSH key.
   • bastion-host-external-ip: 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 lets you 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. Replace bastion-host-instance-name with the name of the bastion host instance that you're using to gain access to your internal network.

   gcloud compute ssh --ssh-flag="-A" bastion-host-instance-name
   

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

   $ ssh username@internal-instance-ip-address

   Replace the following:

   • username: The name attached to your SSH key.
   • internal-instance-ip-address: The internal IP address of the instance that you want to connect to.

After you connect, run commands on your instance using this terminal. When you finish, disconnect from the instance by running the exit command.

Windows

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 VM 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 does not have an external IP address by using SSH:

   $ ssh username@internal-ip-address
   

   Replace the following:

   • username: 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: The internal IP address of the instance that you want to connect to.

   After you connect, run commands on your instance using this terminal. When you finish, disconnect from the instance by running the exit command.

Connecting through IAP

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

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

Connecting to instances as the root user

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

As a best practice, the /etc/ssh/sshd_config SSH configuration file has the PermitRootLogin parameter set to no. Because of this parameter, you cannot 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

Replace the following:

• project-id: The ID of the project that contains the instance.
• zone: The name of the zone in which the instance is located.
• instance-name: The name of the instance.

Connecting to Windows instances using the PowerShell terminal

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

1. If you have not 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 Google Cloud 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 do not 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. Replace ip-address with the external IP address, DNS name, or Windows computer name for the instance to which you want to connect.

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

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

After you connect, 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

Replace the following:

• ip-address: The IP address, DNS name, or Windows computer name for the instance to which you want to connect.
• script: 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, letting you 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 OS Login roles necessary to connect 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 tool on Instance A to create a chain-SSH connection to Instance B. The gcloud tool identifies that Instance B is enabled to use OS Login and also identifies that the service account has the necessary IAM roles for SSH 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.