This document describes how to use a
service account to connect to
Compute Engine virtual machine (VM) instances using SSH. Setting up SSH for a
service account enables you to
configure apps to use SSH, which
can help you to automate your workloads.
If you haven't already, set up authentication.
Authentication verifies your identity for access to Trusted Cloud by S3NS services and APIs. To run
code or samples from a local development environment, you can authenticate to
Compute Engine by selecting one of the following options:
The service account also requires the
compute.projects.setCommonInstanceMetadata permission.
Use the gcloud CLI
--impersonate-service-account flag
to connect directly to a VM using a service account's identity. Run the
following command to connect to a VM as a service account:
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-26 UTC."],[[["\u003cp\u003eThis document explains how to use a service account to connect to Compute Engine virtual machine (VM) instances using SSH, which helps automate workloads.\u003c/p\u003e\n"],["\u003cp\u003eConnecting to VMs as a service account can be done by directly impersonating the service account using the \u003ccode\u003egcloud\u003c/code\u003e CLI with the \u003ccode\u003e--impersonate-service-account\u003c/code\u003e flag, requiring specific permissions such as the Service Account Token Creator role.\u003c/p\u003e\n"],["\u003cp\u003eYou can also impersonate a service account from within a VM, requiring the Service Account User role and the \u003ccode\u003ecompute.projects.setCommonInstanceMetadata\u003c/code\u003e permission, if OS login is not used.\u003c/p\u003e\n"],["\u003cp\u003eBefore connecting to VMs, you must authenticate and may need to set up a default region and zone.\u003c/p\u003e\n"],["\u003cp\u003eSpecific service accounts require different permissions depending on the context, these including but not limited to the OS Login IAM roles, Service Account Token Creator role and Service Account User role.\u003c/p\u003e\n"]]],[],null,["# Connect using service accounts\n\n*** ** * ** ***\n\nThis document describes how to use a\n[service account](/compute/docs/access/service-accounts) to connect to\nCompute Engine virtual machine (VM) instances using SSH. Setting up SSH for a\nservice account enables you to\n[configure apps to use SSH](/compute/docs/tutorials/service-account-ssh), which\ncan help you to automate your workloads.\n\nBefore you begin\n----------------\n\n- [Create a service account](/iam/docs/creating-managing-service-accounts#creating).\n- If you haven't already, set up [authentication](/compute/docs/authentication). Authentication verifies your identity for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:\n 1.\n [Install](/sdk/docs/install) the Google Cloud CLI.\n\n After installation,\n [initialize](/sdk/docs/initializing) the Google Cloud CLI by running the following command:\n\n ```bash\n gcloud init\n ```\n\n\n If you're using an external identity provider (IdP), you must first\n [sign in to the gcloud CLI with your federated identity](/iam/docs/workforce-log-in-gcloud).\n | **Note:** If you installed the gcloud CLI previously, make sure you have the latest version by running `gcloud components update`.\n 2. [Set a default region and zone](/compute/docs/gcloud-compute#set_default_zone_and_region_in_your_local_client).\n\nManually connect to VMs as a service account\n--------------------------------------------\n\nTo connect to VMs as a service account, use one of the following methods:\n**Note:** If you are connecting from a machine that is hosted outside of Google Cloud you must directly impersonate the service account. \n\n### Directly impersonate service account\n\n\n#### Permissions required for this task\n\nTo perform this task, you must have the following\n[permissions](/iam/docs/overview#permissions):\n\n\n- All the permissions included in the [Service Account Token Creator role (`roles/iam.serviceAccountTokenCreator`)](/compute/docs/access/iam#the_serviceaccountuser_role), on the service account. For details about how to grant this role on a singular service account, see [Manage access to service accounts](/iam/docs/manage-access-service-accounts).\n- If you use OS Login, you require all the permissions included one of the [OS Login IAM roles](/compute/docs/oslogin/set-up-oslogin#grant-iam-roles) on the service account.\n- If you don't use OS Login, the service account also requires the `compute.projects.setCommonInstanceMetadata` permission.\n\n\u003cbr /\u003e\n\nUse the gcloud CLI\n[`--impersonate-service-account` flag](/sdk/gcloud/reference#--impersonate-service-account)\nto connect directly to a VM using a service account's identity. Run the\nfollowing command to connect to a VM as a service account: \n\n```\ngcloud compute ssh VM_NAME \\\n --impersonate-service-account=SERVICE_ACCOUNT_EMAIL\n```\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eVM_NAME\u003c/var\u003e: the name of the VM you want to connect to the service account as.\n- \u003cvar translate=\"no\"\u003eSERVICE_ACCOUNT_EMAIL\u003c/var\u003e: the email address associated with the service account.\n\n### Impersonate service account from a VM\n\n\n#### Permissions required for this task\n\nTo perform this task, you must have the following\n[permissions](/iam/docs/overview#permissions):\n\n\n- All permissions included in the [Service Account User role (`roles/iam.serviceAccountUser`)](/compute/docs/access/iam#the_serviceaccountuser_role) on the service account and your user account. For details about how to grant this role on a singular service account, see [Manage access to service accounts](/iam/docs/manage-access-service-accounts).\n- If you use OS Login, you require all the permissions included one of the [OS Login IAM roles](/compute/docs/oslogin/set-up-oslogin#grant-iam-roles) on the service account and your user account.\n- If you don't use OS Login, you also require the `compute.projects.setCommonInstanceMetadata` permission on the service account and your user account.\n\nYou must additionally\n[assign your service account to a VM and set the `cloud-platform` access scope](/compute/docs/access/create-enable-service-accounts-for-instances#changeserviceaccountandscopes)\non the VM.\n\n\u003cbr /\u003e\n\nImpersonate a service account from another VM by doing the following:\n\n1. [Connect to the VM that runs as a service account](/compute/docs/instances/connecting-to-instance#connect_to_vms).\n2. From the VM that runs as a service account, connect to other VMs using\n the same methods.\n\n | **Note:** Connection attempts made from within the VM that runs as the service account use the service account's identity.\n\nWhat's next\n-----------\n\n- Learn how to [configure apps to use SSH](/compute/docs/tutorials/service-account-ssh).\n- Learn more about about [how SSH connections work in Compute Engine](/compute/docs/instances/ssh), including SSH key configuration and storage."]]
