Connecting to Instances Using Advanced Methods

The easiest way to connect to Linux and Windows Server instances is to connect using Compute Engine tools. However, in some situations you might want to manage your own credentials, connect to instances using alternative connection paths, or connect to instances using third-party tools.

This guide shows you how to complete the following tasks:

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

Providing public SSH keys to instances

To connect a Linux VM instance, you need your own SSH key, which consists of a unique private SSH key file and a matching public SSH key file. SSH keys are created and managed for you whenever you connect using Compute Engine tools. However, to connect with third-party tools, you must provide your public SSH key to the instance using one of the following options:

• Use OS Login, which allows you to maintain consistent Linux user identity and avoid providing and managing SSH keys across VM instances.
• Use IAM roles to manage instance access, which allows you to provide your public SSH key to the instance through your Google account or a managed user account.
• Add SSH keys to metadata for the project or a specific instance.
• Have another user manually configure your public SSH key for you on the instance.

After you apply your public SSH key to the instances that you want to connect to, you can use your private SSH key to gain access to the instance.

Connecting using third-party tools

You can access an instance by presenting your private SSH key file through a third-party tool. If you are on a Linux or macOS workstation, you can use the ssh command to connect. However, if you are on a pre-Windows 10 workstation, there is no included tool to present your private SSH key file, so you must download an external tool such as PuTTY. On Chromebooks or operating systems with Chrome installed, you can use the Secure Shell App to establish SSH connections.

SSH

To connect to an instance using the ssh command:

1. Provide your public SSH key to an instance using one of the available options.

2. In the console, find the external IP address for the instance that you want to connect to. Go to the list of your instances.

   Go to the Instances page

3. In a terminal, use the ssh command and your private SSH key file to connect to your instance. Specify your username and the external IP address of the instance that you want to connect to.

   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 name of the user connecting to the instance. The username for your public SSH key was specified when the SSH key was created. You can connect to the instance as that user if the instance has a valid public SSH key for that user and if you have the matching private SSH key.
   • [EXTERNAL_IP_ADDRESS] is the external IP address for your instance.

   If the connection is successful, you can use the terminal to run commands on your instance. When you are done, use the exit command to disconnect from the instance.

SSH App (Chrome OS)

If you cannot SSH from the browser or use the gcloud compute ssh command, you can SSH to instances using the Secure Shell App for Chrome OS or the Chrome Browser.

Install the Secure Shell App in the Chrome browser or on your Chromebook and use it to connect to your instances:

1. Install the Secure Shell App on your Chromebook or the Chrome browser.

2. Identify an existing public SSH key file that you want to use. If you need to generate a new key pair, Open Cloud Shell and use the ssh-keygen command to create the new key pair. You can download that key pair to your local workstation through Cloud Shell.

3. Provide your public SSH key to an instance using one of the available options.

4. In the Google Cloud Platform Console, find the external IP address for the instance that you want to connect to. Go to the list of your instances.

   Go to the Instances page

5. Open the Secure Shell App in a Chrome browser tab.

6. Enter your username and the external IP address for your instance in the following format:

      [USERNAME]@[EXTERNAL_IP_ADDRESS]

   where:

   • [USERNAME] is the name of the user connecting to the instance. The username for your SSH key was specified when the SSH key was created. You can connect to the instance as that user if the instance has a valid public SSH key for that user and if you have the matching private SSH key.
   • [EXTERNAL_IP_ADDRESS] is the external IP address of the instance that you want to connect to.

7. In the Identity field, select the private 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.

8. Click Connect to connect to the instance.

   If the connection is successful, you can use the terminal to run commands on your instance. When you are done, use the exit command to disconnect from the instance.

PuTTY (Windows)

To connect to an instance using PuTTY:

1. Provide your public SSH key to an instance using one of the available options.

2. Download putty.exe.

3. Run the PuTTY tool. For this example, simply run the putty.exe file that you downloaded. A window opens where you can configure your connection settings.

4. In the Google Cloud Platform Console, find the external IP address for the instance that you want to connect to. Go to the list of your instances.

   Go to the Instances page

5. In the PuTTY tool, specify your username and the external IP address of the instance that you want to connect to in the Host Name field. In the example below, the username is jane_doe and the external IP address is 203.0.113.2.

   

   Specify your username and the external IP address for your instance in the following format:

      [USERNAME]@[EXTERNAL_IP_ADDRESS]

   where:

   • [USERNAME] is the name of the user connecting to the instance. The username for your SSH key was specified when the SSH key was created. You can connect to the instance as that user if the instance has a valid public SSH key for that user and if you have the matching private SSH key.
   • [EXTERNAL_IP_ADDRESS] is the external IP address of the instance that you want to connect to.

6. On the left side of the PuTTY window, navigate to Connection > SSH > Auth.

7. Set the Private key file for authentication field with the path to your private key file.

   

8. If you plan to connect from the instance to other instances on your Cloud Platform network, enable Allow agent forwarding. For example, you might allow agent forwarding to forward your private SSH key to a bastion host instance and then connect to instances that do not have external IP addresses.

   

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

   If the connection is successful, you can use the terminal to run commands on your instance. When you are done, use the exit command to disconnect from the instance.

Connecting to instances that do not have external IP addresses

You can create instances without external IP addresses to isolate them from external networks. Isolated instances have only internal IP addresses on a Google Cloud Platform Virtual Private Cloud (VPC) network. You can still connect to these instances using one of 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.
• Connect through a bastion host instance to gain access to the internal IP addresses 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.

Note: Your Google Cloud Platform 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

If you have a Virtual Private Network (VPN) that connects from your local on-premises network to your Google Cloud Platform VPC, you can connect directly to the internal IP addresses of your instances.

You can use the gcloud command-line tool, SSH on Linux and macOS, or PuTTY on Windows to connect to instances that do not have external IP addresses.

gcloud

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

If the connection is successful, you can use the terminal to run commands on the internal instance. When you are done, you can use the exit command to close your connections and return to your local workstation.

SSH

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

1. Provide your public SSH key to an instance using one of the available options.

2. Find the internal IP address of the instance that you want to connect to. You can find the address in the Internal IP column on your Instances page.

   Go to the Instances page

3. Connect to the instance without an external IP address by using SSH.

   $ ssh -i ~/.ssh/[PRIVATE_KEY] [USERNAME]@[INTERNAL_INSTANCE_IP_ADDRESS]

   where:

   • [PRIVATE_KEY] is the filename of your private key file.
   • [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.

If the connection is successful, you can use the terminal to run commands on the instance that does not have an external IP address. When you are done, you can use the exit command to close your connections and return to your local workstation.

PuTTY

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

1. Provide your public SSH key to an instance using one of the available options.

2. Find the internal IP address of the instance that you want to connect to. You can find the address in the Internal IP column on your Instances page.

   Go to the Instances page

3. Connect to your instance by using PuTTY. When you connect, specify the internal IP address of the instance that you want to connect to.

   If the connection is successful, you can use the terminal to run commands on the instance that does not have an external IP address. When you are done, you can use the exit command to close your connections and return to your local workstation.

Connecting through a bastion host

A bastion host instance has an external IP address as well as an internal IP address. If you need to access instances on the internal network that do not have external IP addresses, you can connect to a bastion host and then connect to internal instances from that bastion host. Additionally, you can connect from the bastion host instance to instances on other peered VPC networks.

When you connect to other instances from a bastion host instance, you still require a private SSH key. You must forward your private key to the bastion host instance unless the bastion host instance has the gcloud command-line tool installed and configured to manage your private keys for you.

You can use the gcloud command-line tool, SSH on Linux and macOS, or PuTTY on Windows to connect to instances that do not have external IP addresses. For these examples, the bastion host instance must have a Linux operating system.

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.

If you use the gcloud command-line tool, you can connect to instances that do not have external IP addresses without forwarding your private SSH keys to the bastion host. To do this, gcloud must be installed on both your local workstation and the bastion host instance. If you do need to forward your private keys from your local workstation to the bastion host instance, follow the SSH or PuTTY instructions.

To use the gcloud command-line tool to connect to an instance that does not have an external IP address:

1. For the service account on your bastion host instance, set a read/write Compute Engine API access scope.

   (Tip: use --scopes compute-rw.)

2. Grant the necessary IAM permissions to allow your bastion host to access your public SSH key. Choose one of the following options:

   • OS Login:

     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 are using to gain access to the internal network.

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

   gcloud beta compute ssh [INTERNAL_INSTANCE_NAME] --internal-ip
   

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

If the connection is successful, you can use the terminal to run commands on the internal instance. When you are done, you can use the exit command to close each instance connection and return to your local workstation.

SSH

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. 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 using ssh.

   Connect through the Linux bastion host instance and proxy to the internal host instance.

   $ ssh -i ~/.ssh/[PRIVATE_KEY] -o ProxyCommand="ssh -W %h:%p -i ~/.ssh/[PRIVATE_KEY] [USERNAME]@[BASTION_HOST_EXTERNAL_IP_ADDRESS]" [USERNAME]@[INTERNAL_INSTANCE_IP_ADDRESS]

   where:

   • [PRIVATE_KEY] is the filename of your SSH private key.
   • [USERNAME] is the username attached to your SSH key.
   • [BASTION_HOST_EXTERNAL_IP_ADDRESS] is the external IP address of the bastion host instance that you are using to gain access to the internal network.
   • [INTERNAL_INSTANCE_IP_ADDRESS] is the internal IP address of the instance that you want to connect to.

   Alternatively, you can connect through the bastion host instance and forward your private keys to the bastion host using the gcloud compute ssh command within the ssh ProxyCommand. This option allows you to connect to the bastion host instance using the gcloud command-line tool and avoiding the need to add your public key to the bastion host.

   ssh -i ~/.ssh/[PRIVATE_KEY] -o ProxyCommand="gcloud compute ssh [BASTION_HOST_INSTANCE_NAME] -- -W %h:%p" [USERNAME]@[INTERNAL_INSTANCE_IP_ADDRESS]
   

   where:

   • [PRIVATE_KEY] is the filename of your SSH private key.
   • [USERNAME] is the name attached to your SSH key.
   • [BASTION_HOST_INSTANCE_NAME] is the name of the bastion host instance that you are using to gain access to your internal network.
   • [INTERNAL_INSTANCE_IP_ADDRESS] is the internal IP address of the instance that you want to connect to.

If the connection is successful, you can use the terminal to run commands on the instance that does not have an external IP address.When you are done, you can use the exit command to close each instance connection and return to your local workstation.

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. Enable the Allow agent forwarding setting to pass your private SSH key to the bastion host.

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]
   

   where:

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

   If the connection is successful, you can use the terminal to run commands on the instance that does not have an external IP address. When you are done, you can use the exit command to close each instance connection and return to your local workstation.

Connecting to instances as the root user

By default, public images and most common operating systems do not allow root login using SSH. Instances allow you to 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]

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 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 Cloud Platform 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.

   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 VM instances page or run gcloud compute instances list in the gcloud command line tool.

If the connection is successful, 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. For example, you can use the gcloud compute ssh command to SSH from one instance to another instance using the SSH credentials of the service account rather than your own SSH credentials. 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 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 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.