About SSH connections

Compute Engine uses key-based SSH authentication to establish connections to Linux virtual machine (VM) instances and additionally supports certificate-based authentication for OS Login VMs (Preview). You can optionally enable SSH for Windows VMs. By default, passwords aren't configured for local users on Linux VMs.

Before you can connect to a VM, several configurations must be performed. If you use the Trusted Cloud console or the Google Cloud CLI to connect to your VMs, Compute Engine performs these configurations on your behalf.

Metadata-managed SSH connections

Compute Engine uses custom project and/or instance metadata to configure SSH keys and to manage SSH access.

Click each tab to learn more about the configurations Compute Engine performs before it grants SSH connections when you use the Trusted Cloud console, the gcloud CLI, or third-party tools to connect to VMs. If you connect to VMs without using the Trusted Cloud console or the gcloud CLI, you must perform some configurations yourself.

Console

  1. You use the SSH button in the Trusted Cloud console to connect to your VM.
  2. Compute Engine sets a username and creates an ephemeral SSH key pair with the following configuration:
    • Your username is set as the username in your Google Account. For example, if the email address associated with your Google Account is cloudysanfrancisco@gmail.com, then your username is cloudysanfrancisco.
    • Your public and private SSH keys are stored in your browser session.
    • Your SSH key has an expiry of three minutes. Three minutes after Compute Engine creates the key, you can't use the SSH key to connect to the VM anymore.
  3. Compute Engine authenticates your SSH key and grants your connection.
  4. Compute Engine uploads the public SSH key and username to metadata.
  5. Compute Engine retrieves the SSH key and username from metadata, creates a user account with the username, and on Linux VMs, stores the public key in your user's ~/.ssh/authorized_keys file on the VM. On Windows VMs, Compute Engine doesn't store the public key on the VM.
  6. Compute Engine grants your connection.

gcloud

  1. You use the gcloud compute ssh command to connect to your VM.
  2. Compute Engine sets a username and creates a persistent SSH key pair with the following configurations:
    • Your username is set as the username in your local machine.
    • Your public SSH key is stored in project metadata. If Compute Engine can't store the SSH key in project metadata, for example, because block-project-ssh-keys is set to TRUE, Compute Engine stores the SSH key in instance metadata.
    • Your private SSH key is stored on your local machine.
    • Your SSH key doesn't have an expiry. It is used for all future SSH connections you make, unless you configure a new key.
  3. Compute Engine authenticates your SSH key and grants your connection.
  4. Compute Engine uploads the public SSH key and username to metadata.
  5. Compute Engine retrieves the SSH key and username from metadata, creates a user account with the username, and on Linux VMs, stores the public key in your user's ~/.ssh/authorized_keys file on the VM. On Windows VMs, Compute Engine doesn't store the public key on the VM.
  6. Compute Engine grants your connection.

Third-party tools

  1. You create an SSH key pair and username. See Create SSH keys for details.
  2. You upload the public key and username to metadata. See Add SSH keys to VMs that use metadata-based SSH keys for details.
  3. You connect to the VM.
  4. Compute Engine retrieves the SSH key and username from metadata, creates a user account with the username, and on Linux VMs, stores the public key in your user's ~/.ssh/authorized_keys file on the VM. On Windows VMs, Compute Engine doesn't store the public key on the VM.
  5. Compute Engine grants your connection.

What's next?