This document explains how to create a virtual machine (VM) instance that isconfigured to use a user-managed service account. A service account is a specialkind of account typically used by an application or compute workload to makeauthorized API calls.

Service accounts are needed for scenarios where a workload, such as a customapplication, needs to access Google Cloud resources or perform actions withoutend-user involvement. For more information about when to use service accounts,seeBest practices for using service accounts.

If you have applications that need to make calls to Google Cloud APIs,Google recommends that you attach a user-managed service account to the VM on which theapplication or workload is running. Then, you grant the service accountIAM roles, which gives the service account–and,by extension, applications running on the VM–access toGoogle Cloud resources.

• If you haven't already, set upauthentication. 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:

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  1. Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:

     gcloudinit

     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.
  2. Set a default region and zone.

  Terraform

  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:

  gcloudauthapplication-defaultlogin

  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.

  REST

  To 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.

  Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.

  For more information, seeAuthenticate for using REST in the Google Cloud authentication documentation.

Required roles

To get the permissions that you need to create VMs that use service accounts, ask your administrator to grant you the following IAM roles on the project:

• Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1)
• Create Service Accounts (roles/iam.serviceAccountCreator)
• Project IAM Admin (roles/resourcemanager.projectIamAdmin)

For more information about granting roles, seeManage access to projects, folders, and organizations.

These predefined roles contain the permissions required to create VMs that use service accounts. To see the exact permissions that are required, expand theRequired permissions section:

You might also be able to get these permissions withcustom roles or otherpredefined roles.

Overview

It is recommended that you configure service accounts for your VMs asfollows:

1. Create a new user-managed service account rather than using the Compute Engine default service account, and grant IAM roles to that service account for only the resources and operations that it needs.
2. Attach the service account to your VM.
3. Set the cloud platform (https://www.googleapis.com/auth/cloud-platform) scope on your VM. This allows the VM's service account to call the Google Cloud APIs that it has permission to use.
   • If you specify the service account by using the Google Cloud console, set the service account's access scope toAllow full access to all Cloud APIs.
   • If you specify the service account by using the Google Cloud CLI or Compute Engine API, you can use thescopes parameter to set the access scope.

Set up a service account

Create a service account and assign the required IAM roles.Assign as many or as little IAM roles as needed. You can modifythe IAM roles on your service account as needed.

Google recommends that youlimit the privileges of service accountsand regularly check your service account permissions to make sure they areup-to-date.

Use one of the following methods to set up the service account.

resource "google_service_account" "default" {  account_id   = "service-account-id"  display_name = "Service Account"}

Create a VM and attach the service account

After you create the service account, create a VM and attach the service accountthat you created in the previous section. Also set the VM's access scope tocloud-platform.

If you already have an existing VM and you want to configure that VM to use adifferent service account, seeChange the attached service account.

Use one of the following methods to create a VM and attach the service account.

gcloud compute instances createVM_NAME \    --service-account=SERVICE_ACCOUNT_EMAIL \    --scopes=https://www.googleapis.com/auth/cloud-platform

gcloud compute instances create example-vm \    --service-account 123-my-sa@my-project-123.iam.gserviceaccount.com \    --scopes=https://www.googleapis.com/auth/cloud-platform

resource "google_compute_instance" "default" {  name         = "my-test-vm"  machine_type = "n1-standard-1"  zone         = "us-central1-a"  boot_disk {    initialize_params {      image = "debian-cloud/debian-11"    }  }  // Local SSD disk  scratch_disk {    interface = "SCSI"  }  network_interface {    network = "default"    access_config {      // Ephemeral public IP    }  }  service_account {    # Google recommends custom service accounts with `cloud-platform` scope with    # specific permissions granted via IAM Roles.    # This approach lets you avoid embedding secret keys or user credentials    # in your instance, image, or app code    email  = google_service_account.default.email    scopes = ["cloud-platform"]  }}

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances{   "machineType":"zones/MACHINE_TYPE_ZONE/machineTypes/MACHINE_TYPE",   "name":"VM_NAME",      "disks":[      {         "initializeParams":{            "sourceImage":"projects/IMAGE_PROJECT/global/images/IMAGE"         },         "boot":true      }   ],         "networkInterfaces":[      {         "network":"global/networks/NETWORK_NAME"      }   ],     "serviceAccounts": [      {      "email": "SERVICE_ACCOUNT_EMAIL",      "scopes": ["https://www.googleapis.com/auth/cloud-platform"]      }   ],   "shieldedInstanceConfig":{      "enableSecureBoot":"ENABLE_SECURE_BOOT"   }}

Access and use other Google Cloud services

After your VM is configured to use the service account, applications can thenuse the service account to authenticate. The most common method is toauthenticate by usingApplication Default Credentialsand a client library. Some Google Cloud tools such as thegcloud CLI are able to automatically use the serviceaccount to access Google Cloud APIs from a VM. For more information,seeAuthenticate workloads using service accounts.

If a service account is deleted, applications will no longer have access toGoogle Cloud resources through that service account. If you delete the defaultApp Engine and Compute Engine service accounts, your VMs will no longer haveaccess to resources in the project. If you're not sure whether a serviceaccount is being used, Google recommendsdisabling the service accountbefore deleting it. Disabled service accounts can be re-enabled if they arestill needed.

Example: Access Cloud Storage resources from your VM

After you have configured your VM to use a service account that has thestorage.admin role, you can use tools such as the gcloud CLIto manage files that you have stored on Cloud Storage. To access yourCloud Storage resources, complete the following:

1. Ensure that the service account that is attached to your VM has theroles/storage.admin role.

2. If your VM uses a custom OS image,install the gcloud CLI. By default, the gcloud CLI is installedon most public OS images that are provided by Google Cloud.

3. Connect to the VM.

4. From the VM, use theGoogle Cloud CLI tomanage your Cloud Storage resources.

What's next?

• Learn how toauthenticate workloads using service accounts.
• Learn how tochange the service account attached to a VM.
• Learn how tolist and edit service accounts.
• Review thebest practices for working with service accountsand mitigate security risks.