SSH connections to Linux VMs

Compute Engine uses key-based SSH authentication to establish connections to Linux virtual machine (VM) instances. By default, local users with passwords aren't configured on Linux VMs.

Before you can connect to a VM, several configurations must be performed. If you use the Google Cloud Console or the gcloud command-line tool to connect to your VMs, Compute Engine performs these configurations on your behalf. Compute Engine performs different configurations depending on which tool you use to connect and whether you manage access to VMs through metadata or OS Login.

Metadata-managed SSH connections

By default, Compute Engine uses custom project and/or instance metadata to configure SSH keys and to manage SSH access. If you use OS Login, metadata SSH keys are disabled.

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

Console

  1. You use the SSH button in the Google 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 five minutes. Five minutes after Compute Engine creates the key, you can't use the SSH key to connect to the VM anymore.
  3. Compute Engine uploads the public SSH key and username to metadata.
  4. Compute Engine retrieves the SSH key and username from metadata, creates a user account with the username and public key, and stores the public key in your user's ~/.ssh/authorized_keys file on the VM.
  5. 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 uploads the public SSH key and username to metadata.
  4. Compute Engine retrieves the SSH key and username from metadata, creates a user account with the username and public key, and stores the public key in your user's ~/.ssh/authorized_keys file on the VM.
  5. Compute Engine grants your connection.

Third party tools

  1. You create an SSH key pair and username. See Creating a new SSH key for details.
  2. You upload the public key and username to metadata. See Formatting your public SSH key files for Compute Engine SSH key format requirements.
  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 public key, and stores the public key in your user's ~/.ssh/authorized_keys file on the VM.
  5. Compute Engine grants your connection.

OS Login-managed SSH connections

When OS Login is enabled, Compute Engine refuses connections from SSH keys that are stored in metadata.

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

Console

  1. You use the SSH button in the Google 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 the username set by your organization's Cloud Identity or Google Workspace administrator. If your organization hasn't configured a username for you, or your project doesn't belong to an organization, Compute Engine uses your Google Account email, in the following format: 

      USERNAME_DOMAIN_SUFFIX
      For example, if the email associated with your Google Account is cloudysanfrancisco@gmail.com, then your generated username is cloudysanfrancisco_gmail_com.

    • Your public SSH key is stored in your browser session and in your Google Account.
    • Your private SSH key is stored in your browser session.
    • Your SSH key has an expiry of five minutes. Five minutes after Compute Engine creates the key, you can't use the SSH key to connect to the VM anymore.
  3. Compute Engine resolves your provided username to your OS Login account in the VM using NSS service modules.
  4. Compute Engine performs IAM authorization using PAM configurations, to ensure you have the required permissions to connect.
  5. Compute Engine retrieves the SSH key from your user account and provides it to OpenSSH in the VM using the SSH authorized keys command.
  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 the username set by your organization's Cloud Identity or Google Workspace administrator. If your organization hasn't configured a username for you, Compute Engine uses your Google Account email, in the following format:

      USERNAME_DOMAIN_SUFFIX
      For example, if the email associated with your Google Account is cloudysanfrancisco@gmail.com, then your generated username is cloudysanfrancisco_gmail_com.

    • Your public SSH key is stored in your Google Account.
    • You private SSH key is stored on your local machine in the google_compute_engine file.
    • 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 resolves your provided username to your OS Login account in the VM using NSS service modules.
  4. Compute Engine performs IAM authorization using PAM configurations, to ensure you have the required permissions to connect.
  5. Compute Engine retrieves the SSH key from your user account and provides it to OpenSSH in the VM using the SSH authorized keys command.
  6. Compute Engine grants your connection.

Third party tools

  1. You create an SSH key pair. See Creating a new SSH key for details.
  2. You upload your public SSH key to your OS Login profile. See Adding SSH keys to a user account for details.
    • Compute Engine stores your key in your Google Account.
    • Compute Engine configures your username in the default format: 
          USERNAME_DOMAIN_SUFFIX
      For example, if the email associated with your Google Account is cloudysanfrancisco@gmail.com, then your generated username is cloudysanfrancisco_gmail_com.
  3. You optionally set a username with the Google Workspace Admin SDK Directory API.
  4. You connect to the VM.
  5. Compute Engine resolves your provided username to your OS Login account in the VM using NSS service modules.
  6. Compute Engine performs IAM authorization using PAM configurations, to ensure you have the required permissions to connect.
  7. Compute Engine retrieves the SSH key from your user account and provides it to OpenSSH in the VM using the SSH authorized keys command.
  8. Compute Engine grants your connection.

What's next?