Add SSH keys to VMs


This document describes how to add SSH keys to virtual machine (VM) instances that use OS Login and VMs that use metadata-based SSH keys. If you or your organization administrator hasn't enabled OS Login, your VMs use metadata-based SSH keys.

Before you begin

Add keys to VMs that use OS Login

VMs that use OS Login accept SSH keys that are associated with your Google account. You can associate a public SSH key with your Google account using the gcloud tool or using the OS Login API. If you're an administrator for your organization, you can add SSH keys to user accounts using the Directory API.

When you add SSH keys to your Google account, Compute Engine generates a username for you by combining the username and domain from the email associated with your Google Account. For example, if your email address is cloudysanfrancisco@gmail.com, your username is cloudysanfrancisco_gmail_com. If you add an SSH key in a project that is outside of your organization, your username is prefixed with ext_, for example, ext_cloudysanfrancisco_gmail_com. Your organization administrator can customize your username using the Directory API. If you already have a username configured, Compute Engine uses that username when you add SSH keys.

gcloud

To add a public SSH key to your account use the gcloud compute os-login ssh-keys add command:

gcloud compute os-login ssh-keys add \
    --key-file=KEY_FILE_PATH \
    --project=PROJECT \
    --ttl=EXPIRE_TIME

Replace the following:

  • KEY_FILE_PATH: the path to the public SSH key on your workstation. The key must use the public-openssh format
  • PROJECT: Optional: a project where you intend to use your SSH key. Specify this field to use your SSH key in a project outside of your organization, or you are not a member of a Cloud Identity organization
  • EXPIRE_TIME: Optional: the expiration time for the SSH key

    For example, if you specify 30m the SSH key expires after 30 minutes.

    This flag uses the following units:

    • s for seconds
    • m for minutes
    • h for hours
    • d for days

API

To add a public SSH key to your account use the OS Login API users.importSshPublicKey method:

POST https://oslogin.googleapis.com/v1/users/ACCOUNT_EMAIL:importSshPublicKey

{
 "key": "SSH_KEY",
 "expirationTimeUsec": "EXPIRATION_TIMESTAMP"
}

Replace the following:

  • ACCOUNT_EMAIL: the email address associated with your account
  • SSH_KEY: the public key that you want to add to the account
  • EXPIRATION_TIMESTAMP: the expiration time for the key, in microseconds since epoch (1 second = 106 microseconds)

Add SSH keys to VMs that use metadata-based SSH keys

VMs that don't use OS Login store SSH keys in Compute Engine project and instance metadata. You can use SSH keys stored in project metadata to access all VMs in a project. You can use SSH keys stored in instance metadata to access individual VMs.

You can add a public SSH key to project or instance metadata using the Cloud Console, the gcloud tool, or the Compute Engine API.

Add SSH keys to project metadata

You can add a public SSH key to project metadata to access all VMs in a project, except VMs that block project-wide SSH keys. For more information about blocking project-wide SSH keys, see Block SSH keys from VMs that use metadata-based SSH keys.

Console

To add a public SSH key to project metadata using the Cloud Console, do the following:

  1. In the Cloud Console, go to the Metadata page.

    Go to Metadata

  2. Under SSH Keys, click Edit.

  3. Click Add item. A text box opens.

  4. Add your public key in the text box. The key must be in one of the following formats:

    • Format for a key without an expiration time:

      KEY_VALUE USERNAME
    • Format for a key with an expiration time:

      KEY_VALUE google-ssh {"userName":"USERNAME","expireOn":"EXPIRE_TIME"}

    Replace the following:

    • KEY_VALUE: the public SSH key value
    • USERNAME: the username for the SSH key, specified when the key was created
    • EXPIRE_TIME: the time the key expires, in ISO 8601 format. For example: 2021-12-04T20:12:00+0000
  5. Click Save.

gcloud

If there are existing SSH keys in project metadata, you must re-add them to project metadata every time you add a new SSH key using the gcloud tool. If you don't re-add your existing keys, adding a new key erases the existing keys.

To add a public SSH key to project metadata using the gcloud tool, do the following:

  1. If your project already has project-wide public SSH keys, get them from metadata and add them to a new file:

    1. Run the gcloud compute project-info describe command to get the metadata for the project:

      gcloud compute project-info describe
      

      The output is similar to the following:

      ...
      metadata:
      ...
      - key: ssh-keys
        value: |-
          cloudysanfrancisco:ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDAu5kKQCPF...
          baklavainthebalkans:ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDQDx3FNVC8... google-ssh {"userName":"baklavainthebalkans","expireOn":"2021-06-14T16:59:03+0000"}
      ...
      
    2. Copy the ssh-keys metadata value.

    3. Create and open a new text file on your workstation.

    4. In the file, paste the list of keys that you just copied.

    5. Add your new key at the end of the list, in one of the following formats:

      • Format for a key without an expiration time:

        USERNAME:KEY_VALUE
      • Format for a key with an expiration time:

        USERNAME:KEY_VALUE google-ssh {"userName":"USERNAME","expireOn":"EXPIRE_TIME"}

      Replace the following:

      • KEY_VALUE: the public SSH key value
      • USERNAME: the username for the SSH key, specified when the key was created
      • EXPIRE_TIME: the time the key expires, in ISO 8601 format. For example: 2021-12-04T20:12:00+0000
    6. Save and close the file.

  2. Run the gcloud compute project-info add-metadata command to set the project-wide ssh-keys value:

    gcloud compute project-info add-metadata --metadata-from-file=ssh-keys=KEY_FILE
    

    Replace KEY_FILE with one of the following:

    • The path to the file you created in the previous step, if the project had existing SSH keys
    • The path to your new public SSH key file, if the project didn't have existing SSH keys

API

If there are existing SSH keys in project metadata, you must re-add them to project metadata every time you add a new SSH key using the the Compute Engine API. If you don't re-add your existing keys, adding a new key erases the existing keys.

To add a public SSH key to project metadata using the Compute Engine API, do the following:

  1. Get the fingerprint and ssh-keys values from metadata by using the projects.get method

    GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID
    

    Replace PROJECT_ID with your project ID.

    The response is similar to the following:

    ...
    "fingerprint": "utgYE_XWtE8=",
    "items": [
    {
     "key": "ssh-keys",
     "value": "cloudysanfrancisco:ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDAu5kKQCPF...\nbaklavainthebalkans:ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDQDx3FNVC8... google-ssh {"userName":"baklavainthebalkans","expireOn":"2021-06-14T16:59:03+0000"}"
    }
    ]
    ...
    
  2. Add the new ssh-keys value by using the projects.setCommonInstanceMetadata method.

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/setCommonInstanceMetadata
    
    {
    "items": [
     {
      "key": "ssh-keys",
      "value": "EXISTING_SSH_KEYS\nNEW_SSH_KEY"
     }
    ]
    "fingerprint": "FINGERPRINT"
    }
    

    Replace the following:

    • PROJECT_ID: your project ID
    • EXISTING_SSH_KEYS: the value of the ssh-keys key from the response of the projects.get request
    • FINGERPRINT: the value of the fingerprint from the response of the projects.get request
    • NEW_SSH_KEY: the new SSH key, in one of the following formats:

      • Format for a key without an expiration time:

        USERNAME:KEY_VALUE
      • Format for a key with an expiration time:

        USERNAME:KEY_VALUE google-ssh {"userName":"USERNAME","expireOn":"EXPIRE_TIME"}

      Replace the following:

      • KEY_VALUE: the public SSH key value
      • USERNAME: the username for the SSH key, specified when the key was created
      • EXPIRE_TIME: the time the key expires, in ISO 8601 format. For example: 2021-12-04T20:12:00+0000

Add SSH keys to instance metadata

You can add a public SSH key to instance metadata when you create a VM or after you create a VM.

Add SSH keys to instance metadata during VM creation

You can add SSH keys to instance metadata during VM creation, using the Cloud Console, gcloud tool, or Compute Engine API.

Console

To create a VM and add a public SSH key to instance metadata at the same time using the Cloud Console, do the following:

  1. In the Google Cloud Console, go to the Create an instance page.

    Go to Create an instance

  2. Specify the VM details.

  3. Expand the Networking, disks, security, management, sole tenancy section, and do the following:

    1. Expand the Security section.

    2. To add an SSH key for the VM, click Add item.

    3. Add your public key in the text box. The key must be in one of the following formats:

      • Format for a key without an expiration time:

        KEY_VALUE USERNAME
      • Format for a key with an expiration time:

        KEY_VALUE google-ssh {"userName":"USERNAME","expireOn":"EXPIRE_TIME"}

      Replace the following:

      • KEY_VALUE: the public SSH key value
      • USERNAME: the username for the SSH key, specified when the key was created
      • EXPIRE_TIME: the time the key expires, in ISO 8601 format. For example: 2021-12-04T20:12:00+0000
    4. To create and start the VM, click Create.

gcloud

To create a VM and add a public SSH key to instance metadata at the same time using the gcloud tool, use the gcloud compute instances create command:

gcloud compute instances create VM_NAME \
    --metadata=ssh-keys=PUBLIC_KEY
    ...

Replace the following:

  • VM_NAME: the name of the new VM
  • PUBLIC_KEY: your public SSH key, in one of the following formats:

    • Format for a key without an expiration time:

      USERNAME:KEY_VALUE
    • Format for a key with an expiration time:

      USERNAME:KEY_VALUE google-ssh {"userName":"USERNAME","expireOn":"EXPIRE_TIME"}

    Replace the following:

    • KEY_VALUE: the public SSH key value
    • USERNAME: the username for the SSH key, specified when the key was created
    • EXPIRE_TIME: the time the key expires, in ISO 8601 format. For example: 2021-12-04T20:12:00+0000

You can add multiple SSH keys by using the --metadata-from-file=ssh-keys=FILE_PATH flag. In the file, add a list of usernames and public SSH keys in one of the preceding formats.

API

To create a VM and add a public SSH key to instance metadata at the same time using the Compute Engine, construct a POST request to the instances.insert method:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances

Replace the following:

  • PROJECT_ID: the project ID
  • ZONE: the zone of the VM

In the body of the request, provide usernames and public SSH keys in the items property:

...
{
 "items": [
    {
     "key": "ssh-keys",
     "value": "PUBLIC_KEY"
    }
   ]
}
...

Replace PUBLIC_KEY with your public key, in one of the following formats:

  • Format for a key without an expiration time:

    USERNAME:KEY_VALUE
  • Format for a key with an expiration time:

    USERNAME:KEY_VALUE google-ssh {"userName":"USERNAME","expireOn":"EXPIRE_TIME"}

Replace the following:

  • KEY_VALUE: the public SSH key value
  • USERNAME: the username for the SSH key, specified when the key was created
  • EXPIRE_TIME: the time the key expires, in ISO 8601 format. For example: 2021-12-04T20:12:00+0000

You can add multiple SSH keys by adding \n between keys.

Add SSH keys to instance metadata after VM creation

You can add SSH keys to instance metadata after VM creation, using the Cloud Console, gcloud tool, or Compute Engine API.

Console

To add a public SSH key to instance metadata using the Cloud Console, do the following:

  1. In the Cloud Console, go to the VM instances page.

    Go to VM Instances

  2. Click the name of the VM that you want to add an SSH key for.

  3. Click Edit.

  4. Under SSH Keys, click Show and edit. The section expands to show all of the instance-level public SSH keys.

  5. Add your public key into the text box. The key must be in one of the following formats:

    • Format for a key without an expiration time:

      KEY_VALUE USERNAME
    • Format for a key with an expiration time:

      KEY_VALUE google-ssh {"userName":"USERNAME","expireOn":"EXPIRE_TIME"}

    Replace the following:

    • KEY_VALUE: the public SSH key value
    • USERNAME: the username for the SSH key, specified when the key was created
    • EXPIRE_TIME: the time the key expires, in ISO 8601 format. For example: 2021-12-04T20:12:00+0000
  6. Click Save.

gcloud

If there are existing SSH keys in instance metadata, you must re-add them to instance metadata every time you add a new SSH key using the gcloud tool. If you don't re-add your existing keys, adding a new key erases the existing keys.

To add a public SSH key to instance metadata using the gcloud tool, do the following:

  1. If your VM already has instance-level public SSH keys, get them from metadata and add them to a new file:

    1. Run the gcloud compute instances describe command to get the metadata for the VM:

      gcloud compute instances describe VM_NAME
      

      Replace VM_NAME with the name of the VM for which you need to add or remove public SSH keys.

      The output is similar to the following:

      ...
      metadata:
      ...
      - key: ssh-keys
        value: |-
          cloudysanfrancisco:ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDAu5kKQCPF...
          baklavainthebalkans:ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDQDx3FNVC8... google-ssh {"userName":"baklavainthebalkans","expireOn":"2021-06-14T16:59:03+0000"}
      ...
      
    2. Copy the ssh-keys metadata value.

    3. Create and open a new text file on your workstation.

    4. In the file, paste the list of keys that you just copied.

    5. Add your new key at the end of the list, in one of the following formats:

      • Format for a key without an expiration time:

        USERNAME:KEY_VALUE
      • Format for a key with an expiration time:

        USERNAME:KEY_VALUE google-ssh {"userName":"USERNAME","expireOn":"EXPIRE_TIME"}

      Replace the following:

      • KEY_VALUE: the public SSH key value
      • USERNAME: the username for the SSH key, specified when the key was created
      • EXPIRE_TIME: the time the key expires, in ISO 8601 format. For example: 2021-12-04T20:12:00+0000
    6. Save and close the file.

  2. Run the gcloud compute instances add-metadata command to set the ssh-keys value:

    gcloud compute instances add-metadata VM_NAME --metadata-from-file ssh-keys=KEY_FILE
    

    Replace the following:

    • VM_NAME: the VM you want to add the SSH key for
    • KEY_FILE with one of the following:
      • The path to the file you created in the previous step, if the VM had existing SSH keys
      • The path to your new public SSH key file, if the VM didn't have existing SSH keys

API

If there are existing SSH keys in instance metadata, you must re-add them to instance metadata every time you add a new SSH key using the Compute Engine API. If you don't re-add your existing keys, adding a new key erases the existing keys.

To add a public SSH key to instance metadata using the Compute Engine API, do the following:

  1. Get the fingerprint and ssh-keys values from metadata by using the instances.get method.

    GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME
    

    Replace the following:

    • PROJECT_ID: your project ID
    • ZONE: the zone of the VM to add an SSH key
    • VM_NAME: the VM you're adding an SSH key for

    The response is similar to the following:

    ...
    "fingerprint": "utgYE_XWtE8=",
    "items": [
    {
     "key": "ssh-keys",
      "value": "cloudysanfrancisco:ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDAu5kKQCPF...\nbaklavainthebalkans:ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDQDx3FNVC8... google-ssh {"userName":"baklavainthebalkans","expireOn":"2021-06-14T16:59:03+0000"}"
    }
    ]
    ...
    
  2. Add the new ssh-keys value by using the instances.setMetadata method.

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setMetadata
    
    {
    "items": [
     {
      "key": "ssh-keys",
      "value": "EXISTING_SSH_KEYS\nNEW_SSH_KEY"
     }
    ]
    "fingerprint": "FINGERPRINT"
    }
    

    Replace the following:

    • PROJECT_ID: your project ID
    • EXISTING_SSH_KEYS: the value of the ssh-keys key from the response of the instances.get request
    • FINGERPRINT: the fingerprint from the response of the projects.get request
    • NEW_SSH_KEY: the new SSH key, in one of the following formats:

      • Format for a key without an expiration time:

        USERNAME:KEY_VALUE
      • Format for a key with an expiration time:

        USERNAME:KEY_VALUE google-ssh {"userName":"USERNAME","expireOn":"EXPIRE_TIME"}

      Replace the following:

      • KEY_VALUE: the public SSH key value
      • USERNAME: the username for the SSH key, specified when the key was created
      • EXPIRE_TIME: the time the key expires, in ISO 8601 format. For example: 2021-12-04T20:12:00+0000

What's next?