Stay organized with collections Save and categorize content based on your preferences.
Linux Windows
This document describes how to add SSH keys to virtual machine (VM) instances that use
OS Loginand 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.
Key Point: The procedures in this document are optional. If you connect to VMs using the Google Cloud console or the Google Cloud CLI, Compute Engine creates and manages SSH keys on your behalf. Before you beginSelect the tab for how you plan to use the samples on this page:
ConsoleWhen you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloudInstall the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command:
gcloud init
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update
.To use the Terraform samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
Install the Google Cloud CLI.
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update
.
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
For more information, see Set up authentication for a local development environment.
RESTTo use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.
Install the Google Cloud CLI.
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.
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 CLI 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.
To perform this task, you must have the following permissions:
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
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
formatPROJECT
: 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 organizationEXPIRE_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 secondsm
for minutesh
for hoursd
for daysTo add a public SSH key to your account, use the google_client_openid_userinfo
resource along with the google_os_login_ssh_public_key
resource.
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 accountSSH_KEY
: the public key that you want to add to the accountEXPIRATION_TIMESTAMP
: the expiration time for the key, in microseconds since epoch (1 second = 106 microseconds)VMs that don't use OS Login store SSH keys in Compute Engine project and instance metadata. If OS Login is enabled for a VM, then the VM's guest agent ignores the keys stored in 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.
Compute Engine doesn't automatically remove expired SSH keys from metadata at expiration time, but expired keys can't be used to establish new connections to VMs. If you want to remove expired keys from metadata, see Remove SSH keys from VMs that use metadata-based keys.
You can add a public SSH key to project or VM instance metadata using the Google Cloud console, the gcloud CLI, or REST. You can't set zonal metadata values for SSH keys.
Caution: Public SSH keys that you add directly to a VM's~/.ssh/authorized_keys
files might be overwritten by the VM's guest agent. We recommend that you add keys using the supported Google Cloud console, gcloud CLI, or REST methods as described in the following sections. 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.
Permissions required for this taskTo perform this task, you must have the following permissions:
compute.projects.setCommonInstanceMetadata
on the project.iam.serviceAccounts.actAs
on the project. For more information about service account permissions, see Roles for service account authentication.To add a public SSH key to project metadata using the Google Cloud console, do the following:
In the Google Cloud console, go to the Metadata page.
Click the SSH keys tab.
Click Edit.
Click Add item.
In the SSH key field that opens, add your public SSH key. The key must be in one of the following formats:
KEY_VALUE USERNAME
KEY_VALUE google-ssh {"userName":"USERNAME","expireOn":"EXPIRE_TIME"}
Replace the following:
KEY_VALUE
: the public SSH key valueUSERNAME
: your username. For example, cloudysanfrancisco
or cloudysanfrancisco_gmail_com
.
For Linux VMs, the USERNAME
can't be root
, unless you configure your VM to allow root login. For more information, see Connect to Linux VMs as the root user.
For Windows VMs that use Active Directory (AD), the username must be prepended with the AD domain, in the format of DOMAIN\
. For example, the user cloudysanfrancisco
within the ad.example.com
AD has a USERNAME
of example\cloudysanfrancisco
.
EXPIRE_TIME
: the time the key expires, in ISO 8601 format. For example: 2021-12-04T20:12:00+0000
Click Save.
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
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 CLI. 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 CLI, do the following:
If your project already has project-wide public SSH keys, get them from metadata and add them to a new file:
Run the gcloud compute project-info describe
command to get the SSH keys for the project:
gcloud compute project-info describe \ --format="value(commonInstanceMetadata[items][ssh-keys])"
The output is similar to the following:
username:ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ... username:ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ...
Copy the ssh-keys
metadata value.
Create and open a new text file on your workstation.
In the file, paste the list of keys that you just copied.
Add your new key at the end of the list, in one of the following formats:
USERNAME:KEY_VALUE
USERNAME:KEY_VALUE google-ssh {"userName":"USERNAME","expireOn":"EXPIRE_TIME"}
Replace the following:
KEY_VALUE
: the public SSH key valueUSERNAME
: your username. For example, cloudysanfrancisco
, or cloudysanfrancisco_gmail_com
.
For Linux VMs, the USERNAME
can't be root
, unless you configure your VM to allow root login. For more information, see Connecting to instances as the root user.
For Windows VMs that use Active Directory (AD), the username must be prepended with the AD domain, in the format of DOMAIN\
. For example, the user cloudysanfrancisco
within the ad.example.com
AD has a USERNAME
of example\cloudysanfrancisco
.
EXPIRE_TIME
: the time the key expires, in ISO 8601 format. For example: 2021-12-04T20:12:00+0000
Save and close the file.
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:
To add a public SSH key to your project metadata, use the google_compute_project_metadata
resource.
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:
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"}" } ] ...
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 IDEXISTING_SSH_KEYS
: the value of the ssh-keys
key from the response of the projects.get
requestFINGERPRINT
: the value of the fingerprint
from the response of the projects.get
requestNEW_SSH_KEY
: the new SSH key, in one of the following formats:
USERNAME:KEY_VALUE
USERNAME:KEY_VALUE google-ssh {"userName":"USERNAME","expireOn":"EXPIRE_TIME"}
Replace the following:
KEY_VALUE
: the public SSH key valueUSERNAME
: your username. For example, cloudysanfrancisco
, or cloudysanfrancisco_gmail_com
.
For Linux VMs, the USERNAME
can't be root
, unless you configure your VM to allow root login. For more information, see Connecting to instances as the root user.
For Windows VMs that use Active Directory (AD), the username must be prepended with the AD domain, in the format of DOMAIN\
. For example, the user cloudysanfrancisco
within the ad.example.com
AD has a USERNAME
of example\cloudysanfrancisco
.
EXPIRE_TIME
: the time the key expires, in ISO 8601 format. For example: 2021-12-04T20:12:00+0000
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 creationYou can add SSH keys to instance metadata during VM creation, using the Google Cloud console, gcloud CLI, or Compute Engine API.
ConsoleTo create an instance and add a public SSH key to instance metadata at the same time using the Google Cloud console, do the following:
In the Google Cloud console, go to the Create an instance page.
To add a public SSH key to instance metadata, do the following:
In the navigation menu, click Security.
Expand the Manage access section.
To disable OS Login, clear the Control VM access through IAM permissions checkbox.
If you want to allow public SSH keys in project metadata to access the instance, clear the Block project-wide SSH keys checkbox.
In the Add manually generated SSH keys section, click Add item.
Add your public key in the text box. The key must be in one of the following formats:
KEY_VALUE USERNAME
KEY_VALUE google-ssh {"userName":"USERNAME","expireOn":"EXPIRE_TIME"}
Replace the following:
KEY_VALUE
: the public SSH key valueUSERNAME
: your username. For example, cloudysanfrancisco
or cloudysanfrancisco_gmail_com
.
For Linux VMs, the USERNAME
can't be root
, unless you configure your VM to allow root login. For more information, see Connect to Linux VMs as the root user.
For Windows VMs that use Active Directory (AD), the username must be prepended with the AD domain, in the format of DOMAIN\
. For example, the user cloudysanfrancisco
within the ad.example.com
AD has a USERNAME
of example\cloudysanfrancisco
.
EXPIRE_TIME
: the time the key expires, in ISO 8601 format. For example: 2021-12-04T20:12:00+0000
Optional: Specify other configuration options. For more information, see Configuration options during instance creation.
To create and start the instance, click Create.
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
To create a VM and add a public SSH key to instance metadata at the same time using the gcloud CLI, 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 VMPUBLIC_KEY
: your public SSH key, in one of the following formats:
USERNAME:KEY_VALUE
USERNAME:KEY_VALUE google-ssh {"userName":"USERNAME","expireOn":"EXPIRE_TIME"}
Replace the following:
KEY_VALUE
: the public SSH key valueUSERNAME
: your username. For example, cloudysanfrancisco
, or cloudysanfrancisco_gmail_com
.
For Linux VMs, the USERNAME
can't be root
, unless you configure your VM to allow root login. For more information, see Connecting to instances as the root user.
For Windows VMs that use Active Directory (AD), the username must be prepended with the AD domain, in the format of DOMAIN\
. For example, the user cloudysanfrancisco
within the ad.example.com
AD has a USERNAME
of example\cloudysanfrancisco
.
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.
To add a public SSH key to your instance metadata, use the google_compute_instance
resource.
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 IDZONE
: the zone of the VMIn 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:
USERNAME:KEY_VALUE
USERNAME:KEY_VALUE google-ssh {"userName":"USERNAME","expireOn":"EXPIRE_TIME"}
Replace the following:
KEY_VALUE
: the public SSH key valueUSERNAME
: your username. For example, cloudysanfrancisco
, or cloudysanfrancisco_gmail_com
.
For Linux VMs, the USERNAME
can't be root
, unless you configure your VM to allow root login. For more information, see Connecting to instances as the root user.
For Windows VMs that use Active Directory (AD), the username must be prepended with the AD domain, in the format of DOMAIN\
. For example, the user cloudysanfrancisco
within the ad.example.com
AD has a USERNAME
of example\cloudysanfrancisco
.
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.
You can add SSH keys to instance metadata after VM creation, using the Google Cloud console, gcloud CLI, or Compute Engine API.
Permissions required for this taskTo perform this task, you must have the following permissions:
compute.instances.setMetadata
on the VMTo add a public SSH key to instance metadata using the Google Cloud console, do the following:
In the Google Cloud console, go to the VM instances page.
Click the name of the VM that you want to add an SSH key for.
Click Edit.
Under SSH Keys, click Add item.
Add your public key into the text box. The key must be in one of the following formats:
KEY_VALUE USERNAME
KEY_VALUE google-ssh {"userName":"USERNAME","expireOn":"EXPIRE_TIME"}
Replace the following:
KEY_VALUE
: the public SSH key valueUSERNAME
: your username. For example, cloudysanfrancisco
or cloudysanfrancisco_gmail_com
.
For Linux VMs, the USERNAME
can't be root
, unless you configure your VM to allow root login. For more information, see Connect to Linux VMs as the root user.
For Windows VMs that use Active Directory (AD), the username must be prepended with the AD domain, in the format of DOMAIN\
. For example, the user cloudysanfrancisco
within the ad.example.com
AD has a USERNAME
of example\cloudysanfrancisco
.
EXPIRE_TIME
: the time the key expires, in ISO 8601 format. For example: 2021-12-04T20:12:00+0000
Click Save.
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
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 CLI. 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 CLI, do the following:
If your VM already has instance-level public SSH keys, get them from metadata and add them to a new file:
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"}
...
Copy the ssh-keys
metadata value.
Create and open a new text file on your workstation.
In the file, paste the list of keys that you just copied.
Add your new key at the end of the list, in one of the following formats:
USERNAME:KEY_VALUE
USERNAME:KEY_VALUE google-ssh {"userName":"USERNAME","expireOn":"EXPIRE_TIME"}
Replace the following:
KEY_VALUE
: the public SSH key valueUSERNAME
: your username. For example, cloudysanfrancisco
, or cloudysanfrancisco_gmail_com
.
For Linux VMs, the USERNAME
can't be root
, unless you configure your VM to allow root login. For more information, see Connecting to instances as the root user.
For Windows VMs that use Active Directory (AD), the username must be prepended with the AD domain, in the format of DOMAIN\
. For example, the user cloudysanfrancisco
within the ad.example.com
AD has a USERNAME
of example\cloudysanfrancisco
.
EXPIRE_TIME
: the time the key expires, in ISO 8601 format. For example: 2021-12-04T20:12:00+0000
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 forKEY_FILE
with one of the following: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:
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 IDZONE
: the zone of the VM to add an SSH keyVM_NAME
: the VM you're adding an SSH key forThe 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"}" } ] ...
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 IDEXISTING_SSH_KEYS
: the value of the ssh-keys
key from the response of the instances.get
requestFINGERPRINT
: the fingerprint
from the response of the projects.get
requestNEW_SSH_KEY
: the new SSH key, in one of the following formats:
USERNAME:KEY_VALUE
USERNAME:KEY_VALUE google-ssh {"userName":"USERNAME","expireOn":"EXPIRE_TIME"}
Replace the following:
KEY_VALUE
: the public SSH key valueUSERNAME
: your username. For example, cloudysanfrancisco
, or cloudysanfrancisco_gmail_com
.
For Linux VMs, the USERNAME
can't be root
, unless you configure your VM to allow root login. For more information, see Connecting to instances as the root user.
For Windows VMs that use Active Directory (AD), the username must be prepended with the AD domain, in the format of DOMAIN\
. For example, the user cloudysanfrancisco
within the ad.example.com
AD has a USERNAME
of example\cloudysanfrancisco
.
EXPIRE_TIME
: the time the key expires, in ISO 8601 format. For example: 2021-12-04T20:12:00+0000
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-08-07 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-07 UTC."],[[["This document details how to add SSH keys to virtual machines (VMs) using OS Login or metadata-based SSH keys, which is an optional procedure as Google Cloud can create and manage them for you."],["You can add SSH keys to your Google Account for VMs that use OS Login, which generates a username based on your account email, or to project and instance metadata for VMs not using OS Login."],["Adding SSH keys to project metadata allows access to all VMs in a project, while adding them to instance metadata grants access to specific VMs."],["When adding new SSH keys through the gcloud CLI or REST, you need to re-add any existing SSH keys, to avoid erasing them, while also providing the ability to include an expiration time for the key."],["Methods to add SSH Keys to VMs can be done through the Google Cloud Console, gcloud CLI, Terraform, or REST API."]]],[]]
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4