Connecting to Linux Instances

This guide shows you how to connect to Linux instances using common SSH tools on Linux, macOS, and Windows workstations. If you need to connect to a Windows instance, see Connecting to Windows Instances.

The easiest way to connect to a Linux instance is to connect with Compute Engine tools. When you connect through Compute Engine tools, access to your Linux instances is determined by Identity and Access Management (IAM) roles. If you have the correct IAM roles, you can use Compute Engine tools to connect to any Linux instance in your project.

Alternatively, you can connect to your Linux instances through third-party tools. When you connect through third-party tools, you control access to your Linux instances by managing SSH keys. Use third-party tools to connect to your Linux instances if you want to specify which instances each user can access and give access to users without adding them to your Compute Engine project.

Regardless of which tools you decide to use, you must follow special instructions if you are trying to connect to a Linux instance that does not have an external IP address. Additionally, you cannot connect to a Linux instance as the root user.

Before you begin

Connecting using Compute Engine tools

To connect to a Linux VM instance, you must have an SSH key. Compute Engine will manage your SSH keys for you whenever you connect to a Linux instance from the browser (via the Google Cloud Platform Console) or the gcloud command-line tool, creating and applying SSH keys when needed.

You cannot control user access by managing the SSH keys that are used to connect from the browser or gcloud command-line tool. Instead, user access to connect from browser and gcloud command-line tool is controlled by Identity and Access Management (IAM) roles. The members and IAM roles for a project can be viewed from the IAM page in the Cloud Platform Console:

Go to the IAM page

To connect through the browser or the gcloud command-line tool, you must be a project member who is a Compute Instance Admin. If your instance can run as a service account, you must also be a Service Account Actor. If you do not have access to connect through the browser or gcloud command-line tool, ask a project owner to add you to the project and grant you access.

Once you have been granted access, you can connect to a Linux instance from your browser or, if you prefer to work from a terminal, connect with the gcloud command-line tool.

Connecting to an instance from your browser

Once you have been granted access to a project, you can connect to a Linux instance from the Google Cloud Platform Console.

  1. In the Cloud Platform Console, go to the VM Instances page.

    Go to the VM Instances page

  2. In the list of virtual machine instances, click SSH in the row of the instance that you want to connect to.

You can now use the terminal to run commands on your Linux instance. When you are done, use the exit command to disconnect from the instance.

Connecting to an instance through the command line

Once you have you have been granted access to a project and have installed the gcloud command-line tool, you can connect to a Linux instance by using the gcloud compute ssh command in a terminal on your local workstation:

gcloud compute ssh [INSTANCE_NAME]

where [INSTANCE_NAME] is the name of the instance.

After you connect, you can use the terminal to run commands on your Linux instance. When you are done, use the exit command to disconnect from the instance.

Connecting using third-party tools

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 with Compute Engine tools. However, to connect with third-party tools, you must create and manage SSH keys yourself.

After you obtain an SSH key and apply the public SSH key file to the instances that you want to connect to, you can access an instance by presenting your private SSH key file from 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 Windows workstation, there is no included tool to present your private SSH key file, so you will have to download an external tool such as PuTTY.

SSH (Linux & macOS)

To connect to an instance using ssh:

  1. If you have not yet applied a public key to your Cloud Platform Console project or instance, obtain an SSH key and apply the public SSH key file.

  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.

PuTTY (Windows)

To connect to an instance using PuTTY:

  1. If you have not yet applied a public key to your Cloud Platform Console project or instance, obtain an SSH key and apply the public SSH key file.

  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.

    Setting the Host Name field with jane_doe@203.0.113.2

    Enter your username and the external IP address 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.

    Setting the path to the my-ssh-key.ppk file in the private key file field.

  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.

    Allowing agent forwarding for the instance that you are connecting to.

  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:

Connecting to internal IP addresses 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 beta compute ssh command with the --internal-ip flag.

    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 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. If you have not yet applied a public SSH key to your Cloud Platform Console instance or project, generate a new SSH key and apply it to your project.

  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 all SSH commands for authentication.

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

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

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

  5. Connect to the instance without 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.

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. If you have not yet applied a public key to your Cloud Platform Console instance or project, generate a new SSH key and apply it to your project.

  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 to internal IP addresses 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. For these examples, the bastion host instance must have a Linux operating system.

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.

gcloud

If you have the gcloud command-line tool installed on both your local workstation and the bastion host instance, you can connect to instances that do not have external IP addresses without forwarding your private SSH keys to the bastion host. If you 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. Connect to the 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.

  2. Use the gcloud beta compute ssh command with the --internal-ip flag to connect to instances over their internal IP addresses.

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

    where:

    • [USERNAME] is the name attached to your SSH key.
    • [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

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. If you have not yet applied a public SSH key to your Cloud Platform Console instance or project, generate a new SSH key and apply it to your project.

  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.

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

  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]

    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.

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. If you have not yet applied a public key to your Cloud Platform Console instance or project, generate a new SSH key and apply it to your project.

  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 your connections 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 over SSH. 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 instances 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.

What's next

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Compute Engine Documentation