Adding and Removing SSH Keys

This guide shows you how to use the gcloud tool or API methods to add or remove project-wide SSH keys or instance-only SSH keys. You can use the gcloud tool or the API methods to automate SSH key management across the instances in your project rather than letting Compute Engine manage your keys for you. Users with these SSH keys are administrators on your instances that can run commands with sudo. By default, SSH access to instances as the root user is disabled even if you specify an SSH key in project or instance metadata for root.

If you simply need to connect to your Linux instances, see Connecting to Linux Instances. If you need to connect to a Windows instance, see Connecting to Windows instances.

Before you begin

Overview

When you add or remove SSH keys, you set a project or instance metadata value. To remove keys, you obtain your existing metadata value and copy it to a string, remove keys from that string, and then set the metadata value again with the modified string. The process to add keys is the same, but you add keys to the string rather than remove keys from the string.

To set your SSH key metadata values properly use the following process:

  1. Determine which metadata values you need to use for your projects or instances.

  2. If you need to add keys, prepare your SSH keys with one of the following processes.

  3. Depending on which metadata values you need, add or remove your SSH keys with one of the following processes:

  4. Connect to the instance to ensure that the new SSH keys work.

Creating a new SSH key-pair with the correct format

If you need a new SSH key file and a matching public key, generate a new SSH key-pair and format the public key to work in Compute Engine metadata.

Linux and OSX


On Linux or OSX workstations, you can generate a key-pair with the ssh-keygen tool.

  1. Open a terminal on your workstation and use the ssh-keygen command to generate a new key-pair. Specify the -C flag to add a comment with your Google username.

    ssh-keygen -t rsa -f ~/.ssh/[KEY_FILE_NAME] -C [USERNAME]
    

    where:

    • [USERNAME] is the user for this SSH key.
    • [KEY_FILE_NAME] is the name that you want to use for your key files. For example, a value of my-ssh-key generates a private key file named my-ssh-key and a public key file named my-ssh-key.pub.
  2. If you use the gcloud tool or the API to set public SSH keys, you must prefix the key with your username. Edit the public key file and include the username prefix. For this example, the key includes the username prefix in addition to the username in the key comment.

    [USERNAME]:ssh-rsa [KEY_VALUE] [USERNAME]
    

    where:

    • [USERNAME] is the user for this SSH key.
    • [KEY_VALUE] is the generated SSH key value.

    Optionally, you can set the expiration time for the key by appending google-ssh to the end of the key file followed by the userName and expireOn fields in JSON.

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

    where:

    • [USERNAME] is the user for this SSH key.
    • [KEY_VALUE] is the generated SSH key value.
    • [EXPIRE_TIME] is is a value in RFC3339 format. For example: 2018-12-04T20:12:00+0000
  3. Restrict access to your private key so that only you can read it and nobody can write to it.

    chmod 400 ~/.ssh/[KEY_FILE_NAME]
    

    where [KEY_FILE_NAME] is the name of your private key file.

  4. Apply the public key to a project or apply the public key to a specific instance. The public key file is the file with the .pub extension.

Windows


Windows does not have the ssh-keygen tool built in, so you must use a third-party tool to generate key-pairs if you are on a Windows workstation. For this example, use the PuTTYgen tool to generate key-pairs.

  1. Download puttygen.exe.

  2. Run PuTTYgen. For this example, simply run the puttygen.exe file that you downloaded. A window opens where you can configure your key generation settings.

  3. Click the Generate button to generate a new key-pair. For most cases, the default parameters are fine. When you are done generating the key-pair, the tool displays your public key value.

  4. Optionally, you can enter a Key passphrase to protect your key.

  5. Click Save private key to write your private key to a file with a .ppk extension.

  6. Click Save public key to write your public key to a file with a .pub extension.

  7. If you use the gcloud tool or the API to set public SSH keys, you must prefix the public key with your username. Edit the public key file and include the username prefix. For this example, the key includes a username prefix in addition to the username in the key comment.

    [USERNAME]:ssh-rsa [KEY_VALUE] [USERNAME]
    

    where:

    • [USERNAME] is the user for this SSH key.
    • [KEY_VALUE] is the generated SSH key value.

    Optionally, you can set the expiration time for the key by appending google-ssh to the end of the key file followed by the userName and expireOn fields in JSON.

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

    where:

    • [USERNAME] is the user for this SSH key.
    • [KEY_VALUE] is the generated SSH key value.
    • [EXPIRE_TIME] is is a value in RFC3339 format. For example: 2018-12-04T20:12:00+0000
  8. Apply the public key to a project or apply the public key to a specific instance. The public key file is the file with the .pub extension.

Formatting your existing public SSH key files

Before you can upload your existing public SSH keys to your project or your instance metadata, you must format the public key file with some additional information.

  1. Make a copy of your existing public key file file extension. Use the copy with Compute Engine and keep the original file to use with your other SSH configurations.

  2. If you use the gcloud tool or the API to set public SSH keys, you must prefix the key with your username. Edit the public key file and include the username prefix. For this example, the key includes the username prefix in addition to the username in the key comment.

    [USERNAME]:ssh-rsa [KEY_VALUE] [USERNAME]
    

    where:

    • [USERNAME] is the user for this SSH key.
    • [KEY_VALUE] is the generated SSH key value.

    Optionally, you can set the expiration time for the key by appending google-ssh to the end of the key file followed by the userName and expireOn fields in JSON.

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

    where:

    • [USERNAME] is the user for this SSH key.
    • [KEY_VALUE] is the generated SSH key value.
    • [EXPIRE_TIME] is is a value in RFC3339 format. For example: 2018-12-04T20:12:00+0000

Adding or removing SSH keys for all of the instances in your project

If you want to add a public SSH key to all of the instances in your project, set or modify the project-wide sshKeys metadata value. Only project owners and editors can add project-wide public keys.

gcloud


Add or remove project-wide public keys using the gcloud tool.

  1. Obtain your existing project-wide sshKeys metadata value for your instance.

    gcloud compute project-info describe
    
    ...
    metadata:
      fingerprint: Rq1XCvmRVik=
      items:
      - key: sshKeys
        value: [USERNAME]:ssh-rsa [EXISTING_KEY_VALUE_1] [USERNAME]\n[USERNAME]:ssh-rsa [EXISTING_KEY_VALUE_2] [USERNAME]
    ...

    where:

    • [USERNAME] is the username for your existing keys.
    • [EXISTING_KEY_VALUE_1] and [EXISTING_KEY_VALUE_2] are public key values that are already applied to your project.
  2. Merge your existing keys with any new keys that you are adding, and leave out any keys that you want to delete. For this example, the file contains a new [KEY_VALUE] followed by one of the existing key values that you obtained in the previous step. The [EXISTING_KEY_VALUE_1] is left out, and is removed from the instance in the next step.

    [USERNAME]:ssh-rsa [KEY_VALUE] [USERNAME]
    [USERNAME]:ssh-rsa [EXISTING_KEY_VALUE_2] [USERNAME]
    

    where:

    • [USERNAME] is the username for your existing keys.
    • [KEY_VALUE] is the new key value that you are adding to the project.
    • [EXISTING_KEY_VALUE_1] is a public key values that is already applied to your project, but you need to remove it.
    • [EXISTING_KEY_VALUE_2] is a public key values that is already applied to your project and you want to keep.
  3. Use the compute project-info add-metadata command to set the project-wide sshKeys value. For this example, include the --metadata-from-file flag and specify the path to your file on your local client.

    gcloud compute project-info add-metadata
    --metadata-from-file sshKeys=[KEY_FILE_NAME].pub
    

    where [KEY_FILE_NAME] is the name of your public key file.

API


Add or remove project-wide public keys using the instances.setMetadata method.

  1. Use the projects.get method to obtain the metadata fingerprint value. If you want to keep your existing project-wide keys, obtain the existing sshKeys values.

    GET https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]
    
    ...
    "fingerprint": "[FINGERPRINT]",
    "items": [
     {
      "key": "sshKeys",
      "value": "[USERNAME]:ssh-rsa [EXISTING_KEY_VALUE_1] [USERNAME]\n[USERNAME]:ssh-rsa [EXISTING_KEY_VALUE_2] [USERNAME]"
     }
    ]
    ...

    where:

    • [PROJECT_ID] is your unique project ID.
    • [FINGERPRINT] is the unique ID for this specific metadata configuration, which prevents you from accidentally overwriting concurrent changes.
    • [USERNAME] is the username for your existing keys.
    • [EXISTING_KEY_VALUE_1] and [EXISTING_KEY_VALUE_2] are public key values that are already applied to your project.
  2. Merge your existing keys with any new keys that you are adding, and leave out any keys that you want to delete. For this example, the file contains a new [KEY_VALUE] followed by one of the existing key values that you obtained in the previous step. The [EXISTING_KEY_VALUE_1] is left out, and is removed from the instance in the next step. Use \n characters to separate each key value.

    [USERNAME]:ssh-rsa [KEY_VALUE] [USERNAME]\n[USERNAME]:ssh-rsa [EXISTING_KEY_VALUE_2] [USERNAME]
    

    where:

    • [USERNAME] is the username for your existing keys.
    • [KEY_VALUE] is the new key value that you are adding to the project.
    • [EXISTING_KEY_VALUE_1] is a public key values that is already applied to your project, but you need to remove it.
    • [EXISTING_KEY_VALUE_2] is a public key values that is already applied to your project and you want to keep.
  3. Use the projects.setcommoninstancemetadata method to set the project-wide sshKeys value. Include the fingerprint value, which ensures that you do not overwrite any concurrent changes to this metadata value.

    POST https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/setCommonInstanceMetadata
    
    {
     "items": [
      {
       "key": "sshKeys",
       "value": "[USERNAME]:ssh-rsa [KEY_VALUE] [USERNAME]\n[USERNAME]:ssh-rsa [EXISTING_KEY_VALUE_2] [USERNAME]"
      }
     ]
     "fingerprint": "[FINGERPRINT]"
    }
    

    where:

    • [PROJECT_ID] is your unique project ID.
    • [USERNAME] is the username for your existing keys.
    • [KEY_VALUE] is the new key value that you are adding to the project.
    • [EXISTING_KEY_VALUE_1] is a public key values that is already applied to your project, but you need to remove it.
    • [EXISTING_KEY_VALUE_2] is a public key values that is already applied to your project and you want to keep.
    • [FINGERPRINT] is the fingerprint that you obtained earlier with the projects.get method.

If an instance has the block-project-ssh-keys metadata value set to TRUE or has a deprecated instance-only sshKeys value, the instance ignores all project-wide SSH keys. To apply project-wide keys to that instance, remove the block-project-ssh-keys metadata value from that instance or remove the deprecated instance-only sshKeys value.

Adding or removing SSH keys for a specific instance

If you want to add a public SSH key to a specific instance in your project, set or modify the instance-only ssh-keys metadata value.

gcloud


Add an instance-only public key using the gcloud tool.

  1. Obtain your existing instance-only ssh-keys metadata value for your instance.

    gcloud compute instances describe [INSTANCE_NAME]
    
    ...
    metadata:
      fingerprint: QCofVTHlggs=
      items:
      - key: ssh-keys
        value: [USERNAME]:ssh-rsa [EXISTING_KEY_VALUE_1] [USERNAME]\n[USERNAME]:ssh-rsa [EXISTING_KEY_VALUE_2] [USERNAME]
    ...

    where:

    • [INSTANCE_NAME] is the name of the instance where you need to add additional public SSH keys.
    • [USERNAME] is the username for your existing keys.
    • [EXISTING_KEY_VALUE_1] and [EXISTING_KEY_VALUE_2] are public key values that are already applied to your instance.
  2. Merge your existing keys with any new keys that you are adding, and leave out any keys that you want to delete. For this example, the .pub file contains a new [KEY_VALUE] followed by one of the existing key values that you obtained in the previous step. The [EXISTING_KEY_VALUE_1] is left out, and is removed from the instance in the next step.

    [USERNAME]:ssh-rsa [KEY_VALUE] [USERNAME]
    [USERNAME]:ssh-rsa [EXISTING_KEY_VALUE_2] [USERNAME]
    

    where:

    • [USERNAME] is the username for your existing keys.
    • [KEY_VALUE] is the new key value that you are adding to the instance.
    • [EXISTING_KEY_VALUE_1] is a public key values that is already applied to your instance, but you need to remove it.
    • [EXISTING_KEY_VALUE_2] is a public key values that is already applied to your instance and you want to keep.
  3. Use the compute instances add-metadata command to set the instance-only ssh-key value. For this example, include the --metadata-from-file flag and specify the path to the public key file on your local client.

    gcloud compute instances add-metadata [INSTANCE_NAME] \
    --metadata-from-file ssh-keys=[KEY_FILE_NAME].pub
    

    where:

    • [INSTANCE_NAME] is the name of the instance where you want to apply the public SSH key file.
    • [KEY_FILE_NAME] is the name of your public key file.

API


Add an instance-only sshKeys value in project metadata using the instances.setMetadata method.

  1. Use the instances.get method to obtain the metadata fingerprint value to use for the request. If you want to keep your existing project-wide keys, obtain the existing ssh-keys values.

    GET https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/us-east1-d/instances/[INSTANCE_NAME]
    
    ...
    "fingerprint": "[FINGERPRINT]",
    "items": [
     {
      "key": "ssh-keys",
      "value": "[USERNAME]:ssh-rsa [EXISTING_KEY_VALUE_1] [USERNAME]\n[USERNAME]:ssh-rsa [EXISTING_KEY_VALUE_2] [USERNAME]"
     }
    ]
    ...

    where:

    • [PROJECT_ID] is your unique project ID.
    • [INSTANCE_NAME] is the instance where you want to set the new key.
    • [FINGERPRINT] is the unique ID for this specific metadata configuration, which prevents you from accidentally overwriting concurrent changes.
    • [USERNAME] is the username for your existing keys.
    • [EXISTING_KEY_VALUE_1] and [EXISTING_KEY_VALUE_2] are public key values that are already applied to your instance.
  2. Merge your existing keys with any new keys that you are adding, and leave out any keys that you want to delete. For this example, the file contains a new [KEY_VALUE] followed by one of the existing key values that you obtained in the previous step. The [EXISTING_KEY_VALUE_1] is left out, and is removed from the instance in the next step. Use \n characters to separate each key value.

    [USERNAME]:ssh-rsa [KEY_VALUE] [USERNAME]\n[USERNAME]:ssh-rsa [EXISTING_KEY_VALUE_2] [USERNAME]
    

    where:

    • [USERNAME] is the username for your existing keys.
    • [KEY_VALUE] is the new key value that you are adding to the instance.
    • [EXISTING_KEY_VALUE_1] is a public key values that is already applied to your instance, but you need to remove it.
    • [EXISTING_KEY_VALUE_2] is a public key values that is already applied to your instance and you want to keep.
  3. Use the instances.setMetadata method to set the instance-only ssh-keys value. Include the fingerprint value, which ensures that you do not overwrite any concurrent changes to this metadata value.

    POST https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/us-east1-d/instances/[INSTANCE_NAME]/setMetadata
    
    {
     "items": [
      {
       "key": "ssh-keys",
       "value": "[USERNAME]:ssh-rsa [KEY_VALUE] [USERNAME]\n[USERNAME]:ssh-rsa [EXISTING_KEY_VALUE_1] [USERNAME]\n[USERNAME]:ssh-rsa [EXISTING_KEY_VALUE_2] [USERNAME]"
      }
     ]
     "fingerprint": "[FINGERPRINT]"
    }
    

    where:

    • [PROJECT_ID] is your unique project ID.
    • [INSTANCE_NAME] is the instance where you want to set the new key.
    • [FINGERPRINT] is the unique ID for this specific metadata configuration, which prevents you from accidentally overwriting concurrent changes.
    • [USERNAME] is the username for your existing keys.
    • [EXISTING_KEY_VALUE_1] and [EXISTING_KEY_VALUE_2] are public key values that are already applied to your instance.

Blocking project-level keys from working on specific instances

If you need your instance to ignore project-wide keys and use only the instance-only keys that you set on your instance, set the block-project-ssh-keys metadata value to TRUE.

gcloud


Add the block-project-ssh-keys metadata value to your instance and set it to TRUE. This metadata value blocks all project-wide keys from functioning on this instance so that only instance-only keys will work.

gcloud compute instances add-metadata [INSTANCE_NAME]
--metadata block-project-ssh-keys=TRUE

where [INSTANCE_NAME] is the name of the instance where you want to apply the public SSH key file.

API


Add the block-project-ssh-keys metadata value to your instance and set it to TRUE. This metadata value blocks all project-wide keys from functioning on this instance so that only instance-only keys will work.

 POST https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/us-east1-d/instances/[INSTANCE_NAME]/setMetadata

 {
  "items": [
   {
    "key": "block-project-ssh-keys",
    "value": TRUE
   }
  ]
  "fingerprint": "[FINGERPRINT]"
 }

where:

  • [PROJECT_ID] is your unique project ID.
  • [INSTANCE_NAME] is the instance where you want to set the new key.
  • [FINGERPRINT] is the unique ID for this specific metadata configuration, which prevents you from accidentally overwriting concurrent changes.

What's next

Send feedback about...

Compute Engine Documentation