Change the attached service account

---

This document explains how to configure an existing virtual machine (VM) to use a different service account. A service account is a special kind of account typically used by an application or compute workload to make authorized API calls.

Service accounts are needed for scenarios where a workload, such as a custom application, needs to access Google Cloud resources or perform actions without end-user involvement. For more information about when to use service accounts, see Best 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 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.

Note: When a user connects to a VM, that user can use all of the IAM permissions granted to the service account attached to the VM.

Before you begin

• If you haven't already, set up authentication. Authentication is the process by which your identity is verified for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine as follows.
  

  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, then initialize it by running the following command:

     gcloud init

     Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
  2. Set a default region and zone.

  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, then initialize it by running the following command:

  gcloud init

Required roles

To get the permissions that you need to configure service accounts on your VM, ask your administrator to grant you the Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1) IAM role on the VM or your project. For more information about granting roles, see Manage access.

This predefined role contains the permissions required to configure service accounts on your VM. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to configure service accounts on your VM:

• compute.instances.setServiceAccount
• compute.instances.stop
• compute.instances.start

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:

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, 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 the service account

You can either create a user-managed service account or use the Compute Engine default service account. A user-managed service account is recommended.

For the selected service account, ensure that the required Identity and Access Management (IAM) roles are assigned.

User-managed

If you don't already have a user-managed service account, create a service account. For detailed instruction, see Set up a service account.

Default

If you are familiar with the Compute Engine default service account and want to use the credentials provided by the default service account instead of creating new service accounts, you can grant IAM roles to the default service account.

Before you assign IAM roles to the default service account, note that:

• Granting an IAM role to the default service account affects all VMs that are running as the default service account. For example, if you grant the default service account the roles/storage.objectAdmin role, all VMs running as the default service account with the required access scopes will have permissions granted by the roles/storage.objectAdmin role. Likewise, if you limit access by omitting certain roles, this affects all VMs running as the default service account.

• It is recommended that you remove the basic Editor role for the default service account. The default service account is added as a project editor to projects by default. To use IAM roles, revoke the basic Editor role.

If you are unsure about granting IAM roles to the default service account, create a new user-managed service account instead.

Caution: If you have existing VMs that are currently using the default service account and are relying on editor access, this process requires that you revoke editor access to the account. VMs relying on editor permissions won't be able to use those permissions to access other Google Cloud APIs. Most Google Cloud products provide IAM roles, so you should be able to grant roles to replicate the access provided by project editor but in some cases, certain APIs do not yet support IAM roles. In these cases, you will need to rely on the project editor role for the time being.

Follow these instructions to grant an IAM role to the default service account:

1. In the Google Cloud console, go to the IAM page.

   Go to IAM

2. If prompted, select a project.

3. Look for the service account named Compute Engine Default Service Account.

4. In the Role(s) column, expand the drop down menu for the Compute Engine Default Service Account.

5. Remove Editor access and save your changes.

6. Next, grant IAM roles to the service account.

Any virtual machine instances that are currently running as the default service account will now have access to other Google Cloud APIs according to the IAM roles you granted to the account.

Attach the service account and update the access scope

To change a VM's service account and access scopes, the VM must be temporarily stopped.

If the service account is in a different project than the VM, you must configure the service account for a resource in a different project.

Use one of the following methods to change the service account and access scopes on your VM.

Console

1. Go to the VM instances page.

   Go to VM instances

2. Click the VM instance name for which you want to change the service account.

3. If the VM is not stopped, click Stop. Wait for the VM to be stopped.

4. Click Edit.

5. Scroll down to the Service Account section.

6. From the drop-down list, select the service account to assign to the VM.

   • If you choose a user-managed service account, the VM's access scope defaults to the recommended cloud-platform scope. If you need a different scope for your user-managed service account, use the gcloud CLI or Compute Engine API to attach the service account.
   • If you choose the Compute Engine default service account, you can modify its access scopes in the Google Cloud console.
     • To change scopes, in the Access scopes section, select Set access for each API and set the appropriate scopes for your needs.
     • Recommended If you're not sure of the proper access scopes to set, choose Allow full access to all Cloud APIs and then make sure to restrict access by setting IAM roles on the service account.

7. Click Save to save your changes.

8. Click Start/Resume to restart the VM.

gcloud

1. Stop the VM by using the instances stop command. Replace VM_NAME with the name of your VM instance.

   gcloud compute instances stop VM_NAME
   

2. Attach the service account. To attach the service account, use the instances set-service-account command and provide the VM name, the service account email, and the desired scopes. For more information about setting access scopes, see Best practices.

   gcloud compute instances set-service-account VM_NAME \
     --service-account=SERVICE_ACCOUNT_EMAIL \
     --scopes=SCOPES
   

   Replace the following:

   • SERVICE_ACCOUNT_EMAIL: the email address for the service account that you created. For example: [e-mail]. To view the email address, see Listing service accounts.

     If you want to remove the service account from the VM, use the --no-service-account flag.

   • VM_NAME: the name of the VM instance.

   • SCOPES: a comma-separated list of scope URIs or aliases provided in the description for the --scopes flag.

     If you want to remove all scopes for the VM, use the --no-scopes flag instead.

   For example, the following command assigns the service account [e-mail] to a VM called example-instance and sets access scopes on that VM to allow read/write access to Compute Engine and read-only access to Cloud Storage:

   gcloud compute instances set-service-account example-instance \
     --service-account=[e-mail] \
     --scopes=compute-rw,storage-ro
   

3. Start the VM by using the instances start command. Replace VM_NAME with the name of your VM instance.

   gcloud compute instances start VM_NAME
   

REST

1. Stop the VM by making a POST request using the instances.stop method:

   POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/stop
   

   Replace the following:

   • PROJECT_ID: the project your VM is in
   • ZONE: the zone where your VM is located
   • VM_NAME: the name of the VM you want to stop

2. Attach the service account by making a POST request to the setServiceAccount method:

   POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setServiceAccount
   
   {
     "email": "SERVICE_ACCOUNT_EMAIL",
     "scopes": [
       "SCOPE_URI",
       "SCOPE_URI",
       ...
     ]
   }
   

   Replace the following:

   • PROJECT_ID: the project ID for this request.
   • ZONE: the zone where this VM belongs to.
   • VM_NAME: the name of the VM.
   • SERVICE_ACCOUNT_EMAIL: the email address for the service account that you created. For example: [e-mail]. To view the email address, see Listing service accounts.
   • SCOPE_URI: the required scope URI.

   For example, the following request uses the service account email [e-mail] and sets a Cloud Storage and BigQuery scope:

   POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setServiceAccount
   
   {
     "email": "[e-mail]",
     "scopes": [
       "https://www.googleapis.com/auth/bigquery",
       "https://www.googleapis.com/auth/devstorage.read_only"
     ]
   }
   

3. Start the VM by constructing a POST request using the instances.start method:

   POST https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/start
   

   Replace the following:

   • PROJECT_ID: the project your VM is in
   • ZONE: the zone where your VM is located
   • VM_NAME: the name of the VM you want to start

View the service account that is used by a VM

To view all the service accounts in a project, see Listing service accounts.

If you need to identify the service account that is being used by a VM, complete one of the following procedures:

console

1. Go to the VM instances page.

   Go to VM instances

2. Click the VM instance name for which you want to change the service account.

3. Go to the API and identity management section. This sections displays the service account and access scope that is used by the VM.

gcloud

Run the gcloud compute instances describe command:

gcloud compute instances describe VM_NAME \
    --format json

The output is similar to the following:

{
  ...
  "serviceAccounts":[
      {
        "email":"[e-mail]",
        "scopes":[
            "https://www.googleapis.com/auth/devstorage.full_control"
        ]
      }
  ]
  ...
   }

If the VM isn't using a service account, you receive a response without the serviceAccounts property.

Metadata Server

Query the metadata server from within the VM itself. Make a request to http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/" \
-H "Metadata-Flavor: Google"

If you enabled one or more service accounts when you created the instance, this curl command returns output similar to the following:

[e-mail]/
default/

If the instance isn't using a service account, you receive an empty response.

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