This page describes Compute Engine service accounts and service account permissions, which can be limited by both access scopes that apply to VM instances, and Identity and Access Management (IAM) roles that apply to service accounts. To learn how to create and use service accounts, read the Creating and enabling service accounts for instances documentation.
The following documents describe the best practices for using and securing service accounts:
A service account is a special account that can be used by services and applications running on your Compute Engine instance to interact with other Google Cloud APIs. Apps can use service account credentials to authorize themselves to a set of APIs and perform actions within the permissions granted to the service account and virtual machine instance. In addition, you can create firewall rules that allow or deny traffic to and from instances based on the service account that you associate with each instance.
Try it for yourself
If you're new to Google Cloud, create an account to evaluate how Compute Engine performs in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.Try Compute Engine free
What is a service account?
A service account is an identity that an instance or an application can use to run API requests on your behalf.
This identity is used to identify apps running on your virtual machine instances to other Google Cloud services. For example, if you write an app that reads and writes files on Cloud Storage, it must first authenticate to the Cloud Storage API. You can create a service account and grant the service account access to the Cloud Storage API. Then update your app to pass the service account credentials to the Cloud Storage API. Your app authenticates seamlessly to the API without embedding any secret keys or user credentials in your instance, image, or app code.
If your service accounts have the necessary IAM permissions, those service accounts can create and manage instances and other resources. Service accounts can modify or delete resources only if you grant the necessary IAM permissions to the service account at the project or resource level. You can also change what service account is associated with an instance.
An instance can have only one service account.
Two types of service accounts are available to Compute Engine instances:
- User-managed service accounts
- Google-managed service accounts
User-managed service accounts
User-managed service accounts include new service accounts that you explicitly create and the Compute Engine default service account.
New service accounts
You can create and manage your own service accounts using Identity and Access Management. After you create an account, grant the account IAM roles and set up instances to run as the service account. Apps running on instances enabled with the service account can use the account's credentials to make requests to other Google APIs.
To create and set up a new service account, see Creating and enabling service accounts for instances.
Compute Engine default service account
New projects that have enabled the Compute Engine API have a Compute Engine default service account, which has the following email:
Google creates the Compute Engine default service account and adds it to your project automatically but you have full control over the account.
The Compute Engine default service account is created with the IAM project editor role, but you can modify your service account's roles to control the service account's access to Google APIs.
You can disable or delete this service account from your project, but doing so might cause any applications that depend on the service account's credentials to fail. If you accidentally delete the Compute Engine default service account, you can try to recover the account within 30 days. For more information, see Creating and managing service accounts.
In summary, the Compute Engine default service account has the following attributes:
- Automatically created by the Google Cloud Console project and has an autogenerated name and email address.
- Automatically added to your project with the IAM project editor role.
- Enabled by default on all instances created by the
gcloudcommand-line tool and the Cloud Console. You can override this by specifying another service account when creating the instance or by explicitly disabling service accounts for the instance.
Associating a service account to an instance
When you create an instance using the
gcloud command-line tool or the
Google Cloud Console, you can specify which service account the instance uses
when calling Google Cloud APIs. The instance is automatically
configured with the following access scopes:
- Read-only access to Cloud Storage:
- Write access to write Compute Engine logs:
- Write access to publish metric data to your Google Cloud projects:
- Read-only access to Service Management features required for Google Cloud
- Read/write access to Service Control features required for Google Cloud
Access scopes define the default OAuth scopes for requests made through the
client libraries and gcloud. As a result, they potentially limit access to API
methods when authenticating through OAuth. However, they do not extend to other
authentication protocols like
gRPC. As a result, a best
practice is for you to set the full
access scope on the instance, then control your service account's access
by granting IAM roles to the service account. See
Service account permissions for details.
When you create an instance by making a request to the API directly without using
gcloud command-line tool or the Google Cloud Console, the default service
account does not come enabled with the instance. However, you can still enable
the default service account by explicitly specifying it as part of the request
Google-managed service accounts
These service accounts are created and managed by Google and assigned to your project automatically. These accounts represent different Google services and each account has some level of access to your Google Cloud project.
Google APIs Service Agent
Apart from the default service account, all projects enabled with Compute Engine come with a Google APIs Service Agent, identifiable using the email:
This service account is designed specifically to run internal Google processes on your behalf. The account is owned by Google and is not listed in the Service Accounts section of Cloud Console. By default, the account is automatically granted the project editor role on the project and is listed in the IAM section of Cloud Console. This service account is only deleted when the project is deleted. However, you can change the roles granted to this account, including revoking all access to your project.
Certain resources rely on this service account and the default editor permissions granted to the service account. For example, managed instance groups and autoscaling uses the credentials of this account to create, delete, and manage instances. If you revoke permissions to the service account, or modify the permissions in such a way that it does not grant permissions to create instances, this will cause managed instance groups and autoscaling to stop working.
For these reasons, you should not modify this service account's roles unless a role recommendation explicitly suggests that you modify them.
Compute Engine Service Agent
All projects that have enabled the Compute Engine API have a Compute Engine Service Agent, which has the following email:
This service account is designed specifically for
Compute Engine to perform its service duties on your project.
It relies on the Service Agent IAM Policy granted on your
Google Cloud Project. It is also the service account
Compute Engine uses to
access the customer-owned service account on VM
instances. Google owns this account, but it is specific to your project. This
account is hidden from the IAM page in the
console unless you select Include Google-provided role grants.
By default, the account is automatically granted the
role on your project.
This service account is deleted only when you delete your project. You can change the roles granted to this account and revoke all access to your project from the account. Revoking or changing the permissions for this service account prevents Compute Engine from accessing the identities of your service accounts on your VMs, and can cause outages of software running inside your VMs.
For these reasons, you should avoid modifying the roles for this service account as much as possible.
Service account permissions
When you set up an instance to run as a service account, you determine the level of access the service account has by the IAM roles that you grant to the service account. If the service account has no IAM roles, then no API methods can be run by the service account on that instance.
Furthermore, an instance's access scopes determine the default OAuth scopes for
requests made through the
gcloud tool and client libraries on the instance. As
a result, access scopes potentially further limit access to API methods when
authenticating through OAuth. However, they do not extend to other
authentication protocols like gRPC.
The best practice is to set the full
cloud-platform access scope on the instance, then control the service
account's access using IAM roles.
- IAM restricts access to APIs based on the IAM roles that are granted to the service account.
- Access scopes potentially further limit access to API methods when authenticating through OAuth.
Both access scopes and IAM roles are described in detail in the sections below.
There are many access scopes
that you can choose from but you can also just set the
scope, which is an OAuth scope for most Google Cloud services, and then
control the service account's access by granting it IAM roles.
For example, if you enabled the
cloud-platform access scope on an
instance and then granted the following predefined IAM roles:
Then the service account has only the permissions included in those three IAM roles. That account cannot perform actions outside of these roles despite the Google Cloud access scope.
On the other hand, if you grant a more restrictive scope on the instance, like
the Cloud Storage read-only scope
roles/storage.objectAdmin administrator role on the service
account, then by default, requests from the
gcloud tool and the client
libraries would not be able to manage Cloud Storage objects from that
instance, even though you granted the service account the
roles/storage.ObjectAdmin role. This is because the Cloud Storage
read-only scope does not authorize the instance to manipulate
Cloud Storage data.
Generally, the documentation for each API method lists the scopes
required for that method. For example, the
instances.insert method provides a
list of valid scopes in its
You must grant the appropriate IAM roles to a service account to allow that service account access to relevant API methods.
For example, you can grant a service account the IAM roles for managing Cloud Storage objects, or for managing Cloud Storage buckets, or both, which limits the account to the permissions granted by those roles.
IAM roles are account-specific. That means after you grant an IAM role to a service account, any instance running as that service account can use that role. Also, keep in mind that:
Some IAM roles are currently in Beta.
You must set access scopes on the instance to authorize access.
While a service account's access level is determined by the IAM roles granted to the service account, an instance's access scopes determine the default OAuth scopes for requests made through the
gcloudtool and client libraries on the instance. As a result, access scopes potentially further limit access to API methods when authenticating through OAuth.
Access scopes are the legacy method of specifying permissions for your instance.
They define the default OAuth scopes used in requests from the
gcloud tool or
the client libraries.
You must set up access scopes when you configure an instance to run as a service account.
A best practice is to set the
cloud-platform access scope on the
instance, then control the service account's API access
with IAM roles.
Access scopes apply on a per-instance basis. You set access scopes when creating an instance and the access scopes persists only for the life of the instance.
Access scopes have no effect if you have not enabled the related API on the project that the service account belongs to. For example, granting an access scope for Cloud Storage on a virtual machine instance allows the instance to call the Cloud Storage API only if you have enabled the Cloud Storage API on the project.
Example access scopes include the following:
https://www.googleapis.com/auth/cloud-platform. View and manage your data across most of the Google Cloud services in the specified Google Cloud project.
https://www.googleapis.com/auth/compute. Full control access to Compute Engine methods.
https://www.googleapis.com/auth/compute.readonly. Read-only access to Compute Engine methods.
https://www.googleapis.com/auth/devstorage.read_only. Read-only access to Cloud Storage.
https://www.googleapis.com/auth/logging.write. Write access to the Compute Engine logs.
- Create and enable service accounts for instances.
- Learn more about creating and managing service accounts.
- Learn more about IAM.
- Learn about other Compute Engine access control options.
- Learn how to view audit logs to monitor how your Compute Engine resources are modified.
- If you need to use a service account from a different project, read about configuring service accounts for a resource in a different project.