Create a VM that uses a user-managed service account

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

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 the application or workload is running. Then, you grant the service account IAM roles, which gives the service account–and, by extension, applications running on the VM–access to Google Cloud resources.

Before you begin

If you want to use the command-line examples in this guide, do the following:
1. Install or update to the latest version of the Google Cloud CLI.
2. Set a default region and zone.
If you want to use the API examples in this guide, set up API access.

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 your project:

Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1)
Create Service Accounts (roles/iam.serviceAccountCreator)

For more information about granting roles, see Manage access.

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

Required permissions

The following permissions are required to Create VMs that use service accounts:

To create service accounts: All the permissions in the serviceAccountCreator role
To create VMs:
- compute.instances.create on the project
- compute.instances.updateShieldedVmConfig if you plan to create a Shielded VM instance and you want to be able to change any of the Shielded VM settings
- compute.networks.use on the project if using a legacy network
- compute.subnetworks.use either on the whole project or on the chosen subnet (VPC networks)
- compute.networks.useExternalIp on the project if you need to assign an external IP address (either ephemeral or static) to the instance using a legacy network
- compute.subnetworks.useExternalIp either on the whole project or on the chosen subnet if you need to assign an external IP address (either ephemeral or static) to the instance using a VPC network
- compute.addresses.use on the project if specifying a static address in the project
- compute.instances.setMetadata if setting metadata
- compute.instances.setTags on the instance if setting tags
- compute.instances.setLabels on the instance if setting labels
- compute.instances.setServiceAccount on the instance if setting service account
- compute.images.useReadOnly on the image if creating a new root persistent disk
- compute.disks.create on the project if creating a new root persistent disk with this instance
- compute.disks.useReadOnly on the disk if attaching an existing persistent disk in read-only mode
- compute.disks.use on the disk if attaching an existing disk in read/write mode
- compute.disks.setLabels on the disk if setting labels
- compute.snapshots.create on the project to create a new snapshot if creating an instance from a snapshot
- compute.snapshots.useReadOnly on the snapshot if creating an instance from a snapshot
- compute.instanceTemplates.useReadOnly on the instance template if creating instance from instance template

You might also be able to get these permissions with custom roles or other predefined roles.

Overview

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

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.
Attach the service account to your VM.
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, the VM's access scope automatically defaults to the cloud-platform scope.
- If you specify the service account by using the Google Cloud CLI or Compute Engine API, you can use the scopes 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 modify the IAM roles on your service account as needed.

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

Console

In the Google Cloud console, go to the Create service account page.
Go to Create service account
Select your project.
In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

In the Service account description field, enter a description. For example, Service account for quickstart.
Click Create and continue.
Grant the required roles to the service account.

To grant a role, find the Select a role list, then select the role.

To grant additional roles, click Add another role and add each additional role.

Note: The Role field affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.
Click Continue.
In the Service account users role box, enter the email address for your Google Account.
Click Done to finish creating the service account.

gcloud

Set up authentication:

Create the service account:
```
gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
```
Replace SERVICE_ACCOUNT_NAME with a name for the service account.
To provide access to your project and your resources, grant a role to the service account:
```
gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE
```
Replace the following:
- SERVICE_ACCOUNT_NAME: the name of the service account
- PROJECT_ID: the project ID where you created the service account
- ROLE: the role to grant
Note: The --role flag affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.
To grant another role to the service account, run the command as you did in the previous step.
Grant your Google Account a role that lets you use the service account's roles and attach the service account to other resources:
```
gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:USER_EMAIL" --role=roles/iam.serviceAccountUser
```
Replace the following:
- SERVICE_ACCOUNT_NAME: the name of the service account
- PROJECT_ID: the project ID where you created the service account
- USER_EMAIL: the email address for your Google Account

Terraform

To create a service account, you can use the google_service_account resource.

compute/service_account_for_instances/main.tf

View on GitHub Feedback

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

Remember to replace the placeholder values for the account_id and the display_name attributes.

To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.

Create a VM and attach the service account

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

If you already have an existing VM and you want to configure that VM to use a different service account, see Change the attached service account.

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

Console

In the Google Cloud console, go to the VM instances page.

Go to VM instances

Select your project and click Continue.
Click Create instance.
Specify a Name for your VM.
Scroll to the Identity and API access section.
In the Service account list, select the service account that you created. When you attach a service account to a VM, the Google Cloud access scope cloud-platform access scope is automatically set on the VM.
Make additional VM customizations, as needed.
To create and start the VM, click Create.

gcloud

To create a new VM instance and configure it to use a custom service account by using the Google Cloud CLI, use the gcloud compute instances create command and provide the service account email and the cloud-platform access scope to the VM instance.

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

Replace the following:

SERVICE_ACCOUNT_EMAIL: the email address for the service account that you created. For example: my-sa-123@my-project-123.iam.gserviceaccount.com. To view the email address, see obtain a service account email.
VM_NAME: the name of the VM instance.

For example:

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

You can also specify the scope using the alias: --scopes=cloud-platform. These aliases are recognized only by the gcloud CLI. The API and other libraries do not recognize these aliases, so you must specify the full scope URI.

Terraform

To set up a new VM to use a service account, you can use the google_compute_instance resource.

compute/service_account_for_instances/main.tf

View on GitHub Feedback

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"]
  }
}

API

Use the instances.insert method to create the VM and specify the service account email and access scope for the VM instance.

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"
   }
}

Replace the following:

PROJECT_ID: ID of the project to create the VM in
ZONE: zone to create the VM in
MACHINE_TYPE_ZONE: zone containing the machine type to use for the new VM
MACHINE_TYPE: machine type, predefined or custom, for the new VM
VM_NAME: name of the new VM
IMAGE_PROJECT: project containing the image
For example, if you specify debian-10 as the image family, specify debian-cloud as the image project.
IMAGE or IMAGE_FAMILY: specify one of the following:
- IMAGE: a specific version of a public image
  For example, "sourceImage": "projects/debian-cloud/global/images/debian-10-buster-v20200309"
- IMAGE_FAMILY: an image family
  This creates the VM from the most recent, non-deprecated OS image. For example, if you specify "sourceImage": "projects/debian-cloud/global/images/family/debian-10", Compute Engine creates a VM from the latest version of the OS image in the Debian 10 image family.
NETWORK_NAME: the VPC network that you want to use for the VM. You can specify default to use your default network.
SERVICE_ACCOUNT_EMAIL: the email address for the service account that you created. For example: my-sa-123@my-project-123.iam.gserviceaccount.com. To view the email address, see obtain a service account email.
ENABLE_SECURE_BOOT: Optional: If you chose an image that supports Shielded VM features, Compute Engine, by default, enables the virtual trusted platform module (vTPM) and integrity monitoring. Compute Engine does not enable Secure Boot by default.

If you specify true for enableSecureBoot, Compute Engine creates a VM with all three Shielded VM features enabled. After Compute Engine starts your VM, to modify Shielded VM options, you must stop the VM.

Access and use other Google Cloud services

After your VM is configured to use the service account, applications can then use the service account to authenticate. The most common method is to authenticate by using Application Default Credentials and a client library. Some Google Cloud tools such as gcloud CLI and gsutil are able to automatically use the service account to access Google Cloud APIs from a VM. For more information, see Authenticate workloads using service accounts.

Example: Access Cloud Storage resources from your VM

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

Ensure that the service account that is attached to your VM has the roles/storage.admin role.
If your VM uses a custom OS image, install the gcloud CLI. By default, the gcloud CLI is installed on most public OS images that are provided by Google Cloud.
Connect to the VM.
From the VM, use one of the following tools to manage your Cloud Storage resources.
- Use gsutil
- Use Google Cloud CLI

Best practices

Limit the privileges of service accounts and regularly check your service account permissions to make sure they are up-to-date.
Delete service accounts with caution. Make sure your critical applications are no longer using a service account before deleting it. If you're not sure whether a service account is being used, we recommend disabling the service account instead of deleting it. Disabled service accounts can be re-enabled if they are still needed.
Mitigate the security risks for your service account. For more information, see Best practices for working with service accounts.

What's next?

Review Service account best practices
Review Authenticate workloads using service accounts