IAM overview

Identity and Access Management (IAM) lets you control user and group access to Spanner resources at the project, Spanner instance, and Spanner database levels. For example, you can specify that a user has full control of a specific database in a specific instance in your project, but cannot create, modify, or delete any instances in your project. Using access control with IAM lets you grant a permission to a user or group without having to modify each Spanner instance or database permission individually.

This document focuses on the IAM permissions relevant to Spanner and the IAM roles that grant those permissions. For a detailed description of IAM and its features, see the Identity and Access Management developer's guide. In particular, see its Managing IAM policies section.

Permissions

Permissions allow users to perform specific actions on Spanner resources. For example, the spanner.databases.read permission allows a user to read from a database using Spanner's read API, while spanner.databases.select allows a user to execute a SQL select statement on a database. You don't directly give users permissions; instead, you grant them predefined roles or custom roles, which have one or more permissions bundled within them.

The following tables list the IAM permissions that are associated with Spanner.

Instance configurations

The following permissions apply to Spanner instance configurations. For more information, see the instance configuration references for REST and RPC APIs.

Instance configuration permission name	Description
spanner.instanceConfigs.create	Create a custom instance configuration.
spanner.instanceConfigs.delete	Delete a custom instance configuration.
spanner.instanceConfigs.get	Get an instance configuration.
spanner.instanceConfigs.list	List the set of instance configurations.
spanner.instanceConfigs.update	Update a custom instance configuration.

Instance configuration operations

The following permissions apply to Spanner instance configuration operations. For more information, see the instance references for REST and RPC APIs.

Instance configuration operation permission name	Description
spanner.instanceConfigOperations.list	List instance configuration operations.
spanner.instanceConfigOperations.get	Get a specific instance configuration operation.
spanner.instanceConfigOperations.cancel	Cancel an instance configuration operation.
spanner.instanceConfigOperations.delete	Delete an instance configuration operation.

Instances

The following permissions apply to Spanner instances. For more information, see the instance references for REST and RPC APIs.

Instance permission name	Description
spanner.instances.create	Create an instance.
spanner.instances.list	List instances.
spanner.instances.get	Get the configuration of a specific instance.
spanner.instances.getIamPolicy	Get an instance's IAM Policy.
spanner.instances.update	Update an instance.
spanner.instances.setIamPolicy	Set an instance's IAM Policy.
spanner.instances.delete	Delete an instance.

Instance operations

The following permissions apply to Spanner instance operations. For more information, see the instance references for REST and RPC APIs.

Instance operation permission name	Description
spanner.instanceOperations.list	List instance operations.
spanner.instanceOperations.get	Get a specific instance operation.
spanner.instanceOperations.cancel	Cancel an instance operation.
spanner.instanceOperations.delete	Delete an instance operation.

Partitions

The following permissions apply to Spanner partitions. For more information, see the partition references for REST and RPC APIs.

Instance permission name	Description
spanner.instancePartitions.create	Create a partition.
spanner.instancePartitions.get	Get the configuration of a specific partition.
spanner.instancePartitions.list	List partitions.
spanner.instancePartitions.update	Update a partition.
spanner.instancePartitions.delete	Delete a partition.

Partition operations

The following permissions apply to Spanner partition operations. For more information, see the instance partition references for REST and RPC APIs.

Instance partition operation permission name	Description
spanner.instancePartitionOperations.list	List partition operations.
spanner.instancePartitionOperations.get	Get a specific partition operation.
spanner.instancePartitionOperations.cancel	Cancel a partition operation.
spanner.instancePartitionOperations.delete	Delete a partition operation.

Databases

The following permissions apply to Spanner databases. For more information, see the database references for REST and RPC APIs.

Database permission name	Description
spanner.databases.beginPartitionedDmlTransaction	Execute a Partitioned Data Manipulation Language (DML) statement.
spanner.databases.create	Create a database.
spanner.databases.createBackup	Create a backup from the database. Also requires spanner.backups.create to create the backup resource.
spanner.databases.list	List databases.
spanner.databases.update	Update a database's metadata. Currently unavailable for IAM custom roles.
spanner.databases.updateDdl	Update a database's schema.
spanner.databases.get	Get a database's metadata.
spanner.databases.getDdl	Get a database's schema.
spanner.databases.getIamPolicy	Get a database's IAM Policy.
spanner.databases.setIamPolicy	Set a database's IAM Policy.
spanner.databases.beginReadOnlyTransaction	Begin a read-only transaction on a Spanner database.
spanner.databases.beginOrRollbackReadWriteTransaction	Begin or roll back a read-write transaction on a Spanner database.
spanner.databases.read	Read from a database using the read API.
spanner.databases.select	Execute a SQL select statement on a database.
spanner.databases.write	Write into a database.
spanner.databases.drop	Drop a database.
spanner.databases.useRoleBasedAccess	Use fine-grained access control.
spanner.databases.useDataBoost	Use the compute resources of Spanner Data Boost to process partitioned queries.

Database roles

The following permissions apply to Spanner database roles. For more information, see the database references for REST and RPC APIs.

Database role permission name	Description
spanner.databaseRoles.list	List database roles.
spanner.databaseRoles.use	Use a specified database role.

Database operations

The following permissions apply to Spanner database operations. For more information, see the database references for REST and RPC APIs.

Database operation permission name	Description
spanner.databaseOperations.list	List database and restore database operations.
spanner.databaseOperations.get	Get a specific database operation.
spanner.databaseOperations.cancel	Cancel a database operation.

Backups

The following permissions apply to Spanner backups. For more information, see the backups references for REST and RPC APIs.

Backup permission name	Description
spanner.backups.create	Create a backup. Also requires spanner.databases.createBackup on the source database.
spanner.backups.get	Get a backup.
spanner.backups.update	Update a backup.
spanner.backups.delete	Delete a backup.
spanner.backups.list	List backups.
spanner.backups.restoreDatabase	Restore database from a backup. Also requires spanner.databases.create to create the restored database on the target instance.
spanner.backups.getIamPolicy	Get a backup's IAM policy.
spanner.backups.setIamPolicy	Set a backup's IAM policy.

Backup operations

The following permissions apply to Spanner backup operations. For more information, see the database references for REST and RPC APIs.

Backup operation permission name	Description
spanner.backupOperations.list	List backup operations.
spanner.backupOperations.get	Get a specific backup operation.
spanner.backupOperations.cancel	Cancel a backup operation.

Backup schedules

The following permissions apply to Spanner backup schedules. For more information, see the database references for the REST and RPC APIs.

Backup schedule permission name	Description
spanner.backupSchedules.create	Create a backup schedule. Also requires spanner.databases.createBackup on the source database.
spanner.backupSchedules.get	Get a backup schedule.
spanner.backupSchedules.update	Update a backup schedule.
spanner.backupSchedules.delete	Delete a backup schedule.
spanner.backupSchedules.list	List backup schedules.

Sessions

The following permissions apply to Spanner sessions. For more information, see the database references for REST and RPC APIs.

Note: Sessions are an advanced concept that only apply to users of the REST API and those who are creating their own client libraries. Learn more in Sessions.

Session permission name	Description
spanner.sessions.create	Create a session.
spanner.sessions.get	Get a session.
spanner.sessions.delete	Delete a session.
spanner.sessions.list	List sessions.

Predefined roles

A predefined role is a bundle of one or more permissions. For example, the predefined role roles/spanner.databaseUser contains the permissions spanner.databases.read and spanner.databases.write. There are two types of predefined roles for Spanner:

• Person roles: Granted to users or groups, which allows them to perform actions on the resources in your project.
• Machine roles: Granted to service accounts, which allows machines running as those service accounts to perform actions on the resources in your project.

Note: To avoid providing machines with unnecessarily broad permissions, don't grant person roles to service accounts.

The following table lists the access control with IAM predefined roles, including a list of the permissions associated with each role:

Role	Permissions
Cloud Spanner Admin (roles/spanner.admin) Has complete access to all Spanner resources in a Google Cloud project. A principal with this role can: Grant and revoke permissions to other principals for all Spanner resources in the project. Allocate and delete chargeable Spanner resources. Issue get/list/modify operations on Cloud Spanner resources. Read from and write to all Cloud Spanner databases in the project. Fetch project metadata. Lowest-level resources where you can grant this role: Project	monitoring.timeSeries.list resourcemanager.projects.get resourcemanager.projects.list spanner.* spanner.backupOperations.cancel spanner.backupOperations.get spanner.backupOperations.list spanner.backupSchedules.create spanner.backupSchedules.delete spanner.backupSchedules.get spanner.backupSchedules.getIamPolicy spanner.backupSchedules.list spanner.backupSchedules.setIamPolicy spanner.backupSchedules.update spanner.backups.copy spanner.backups.create spanner.backups.delete spanner.backups.get spanner.backups.getIamPolicy spanner.backups.list spanner.backups.restoreDatabase spanner.backups.setIamPolicy spanner.backups.update spanner.databaseOperations.cancel spanner.databaseOperations.get spanner.databaseOperations.list spanner.databaseRoles.list spanner.databaseRoles.use spanner.databases.beginOrRollbackReadWriteTransaction spanner.databases.beginPartitionedDmlTransaction spanner.databases.beginReadOnlyTransaction spanner.databases.changequorum spanner.databases.create spanner.databases.createBackup spanner.databases.drop spanner.databases.get spanner.databases.getDdl spanner.databases.getIamPolicy spanner.databases.list spanner.databases.partitionQuery spanner.databases.partitionRead spanner.databases.read spanner.databases.select spanner.databases.setIamPolicy spanner.databases.update spanner.databases.updateDdl spanner.databases.updateTag spanner.databases.useDataBoost spanner.databases.useRoleBasedAccess spanner.databases.write spanner.instanceConfigOperations.cancel spanner.instanceConfigOperations.delete spanner.instanceConfigOperations.get spanner.instanceConfigOperations.list spanner.instanceConfigs.create spanner.instanceConfigs.delete spanner.instanceConfigs.get spanner.instanceConfigs.list spanner.instanceConfigs.update spanner.instanceOperations.cancel spanner.instanceOperations.delete spanner.instanceOperations.get spanner.instanceOperations.list spanner.instancePartitionOperations.cancel spanner.instancePartitionOperations.delete spanner.instancePartitionOperations.get spanner.instancePartitionOperations.list spanner.instancePartitions.create spanner.instancePartitions.delete spanner.instancePartitions.get spanner.instancePartitions.list spanner.instancePartitions.update spanner.instances.create spanner.instances.createTagBinding spanner.instances.delete spanner.instances.deleteTagBinding spanner.instances.get spanner.instances.getIamPolicy spanner.instances.list spanner.instances.listEffectiveTags spanner.instances.listTagBindings spanner.instances.setIamPolicy spanner.instances.update spanner.instances.updateTag spanner.sessions.create spanner.sessions.delete spanner.sessions.get spanner.sessions.list
Cloud Spanner Backup Admin (roles/spanner.backupAdmin) A principal with this role can: Create, view, update, and delete backups. View and manage a backup's allow policy. This role cannot restore a database from a backup. Lowest-level resources where you can grant this role: Instance	monitoring.timeSeries.list resourcemanager.projects.get resourcemanager.projects.list spanner.backupOperations.* spanner.backupOperations.cancel spanner.backupOperations.get spanner.backupOperations.list spanner.backupSchedules.create spanner.backupSchedules.delete spanner.backupSchedules.get spanner.backupSchedules.list spanner.backupSchedules.update spanner.backups.copy spanner.backups.create spanner.backups.delete spanner.backups.get spanner.backups.getIamPolicy spanner.backups.list spanner.backups.setIamPolicy spanner.backups.update spanner.databases.createBackup spanner.databases.get spanner.databases.list spanner.instancePartitions.get spanner.instancePartitions.list spanner.instances.createTagBinding spanner.instances.deleteTagBinding spanner.instances.get spanner.instances.list spanner.instances.listEffectiveTags spanner.instances.listTagBindings
Cloud Spanner Backup Writer (roles/spanner.backupWriter) This role is intended to be used by scripts that automate backup creation. A principal with this role can create backups, but cannot update or delete them. Lowest-level resources where you can grant this role: Instance	spanner.backupOperations.get spanner.backupOperations.list spanner.backupSchedules.create spanner.backupSchedules.get spanner.backupSchedules.list spanner.backups.copy spanner.backups.create spanner.backups.get spanner.backups.list spanner.databases.createBackup spanner.databases.get spanner.databases.list spanner.instancePartitions.get spanner.instances.get
Cloud Spanner Database Admin (roles/spanner.databaseAdmin) A principal with this role can: Get/list all Spanner instances in the project. Create/list/drop databases in an instance. Grant/revoke access to databases in the project. Read from and write to all Cloud Spanner databases in the project. Lowest-level resources where you can grant this role: Instance	monitoring.timeSeries.list resourcemanager.projects.get resourcemanager.projects.list spanner.databaseOperations.* spanner.databaseOperations.cancel spanner.databaseOperations.get spanner.databaseOperations.list spanner.databaseRoles.* spanner.databaseRoles.list spanner.databaseRoles.use spanner.databases.beginOrRollbackReadWriteTransaction spanner.databases.beginPartitionedDmlTransaction spanner.databases.beginReadOnlyTransaction spanner.databases.changequorum spanner.databases.create spanner.databases.drop spanner.databases.get spanner.databases.getDdl spanner.databases.getIamPolicy spanner.databases.list spanner.databases.partitionQuery spanner.databases.partitionRead spanner.databases.read spanner.databases.select spanner.databases.setIamPolicy spanner.databases.update spanner.databases.updateDdl spanner.databases.updateTag spanner.databases.useDataBoost spanner.databases.useRoleBasedAccess spanner.databases.write spanner.instancePartitions.get spanner.instancePartitions.list spanner.instances.createTagBinding spanner.instances.deleteTagBinding spanner.instances.get spanner.instances.getIamPolicy spanner.instances.list spanner.instances.listEffectiveTags spanner.instances.listTagBindings spanner.sessions.* spanner.sessions.create spanner.sessions.delete spanner.sessions.get spanner.sessions.list
Cloud Spanner Database Reader (roles/spanner.databaseReader) A principal with this role can: Read from the Spanner database. Execute SQL queries on the database. View schema for the database. Lowest-level resources where you can grant this role: Database	spanner.databases.beginReadOnlyTransaction spanner.databases.getDdl spanner.databases.partitionQuery spanner.databases.partitionRead spanner.databases.read spanner.databases.select spanner.instancePartitions.get spanner.instances.get spanner.sessions.* spanner.sessions.create spanner.sessions.delete spanner.sessions.get spanner.sessions.list
Cloud Spanner Database Role User (roles/spanner.databaseRoleUser) In conjunction with the IAM role Cloud Spanner Fine-grained Access User, grants permissions to individual Spanner database roles. Add a condition for each desired Spanner database role that includes the resource type of `spanner.googleapis.com/DatabaseRole` and the resource name ending with `/YOUR_SPANNER_DATABASE_ROLE`.	spanner.databaseRoles.use
Cloud Spanner Database User (roles/spanner.databaseUser) A principal with this role can: Read from and write to the Spanner database. Execute SQL queries on the database, including DML and Partitioned DML. View and update schema for the database. Lowest-level resources where you can grant this role: Database	spanner.databaseOperations.* spanner.databaseOperations.cancel spanner.databaseOperations.get spanner.databaseOperations.list spanner.databases.beginOrRollbackReadWriteTransaction spanner.databases.beginPartitionedDmlTransaction spanner.databases.beginReadOnlyTransaction spanner.databases.changequorum spanner.databases.getDdl spanner.databases.partitionQuery spanner.databases.partitionRead spanner.databases.read spanner.databases.select spanner.databases.updateDdl spanner.databases.updateTag spanner.databases.write spanner.instancePartitions.get spanner.instances.get spanner.sessions.* spanner.sessions.create spanner.sessions.delete spanner.sessions.get spanner.sessions.list
Cloud Spanner Fine-grained Access User (roles/spanner.fineGrainedAccessUser) Grants permissions to use Spanner's fine-grained access control framework. To grant access to specific database roles, also add the `roles/spanner.databaseRoleUser` IAM role and its necessary conditions.	spanner.databaseRoles.list spanner.databases.useRoleBasedAccess
Cloud Spanner Restore Admin (roles/spanner.restoreAdmin) A principal with this role can restore databases from backups. If you need to restore a backup to a different instance, apply this role at the project level or to both instances. This role cannot create backups. Lowest-level resources where you can grant this role: Instance	monitoring.timeSeries.list resourcemanager.projects.get resourcemanager.projects.list spanner.backups.get spanner.backups.list spanner.backups.restoreDatabase spanner.databaseOperations.* spanner.databaseOperations.cancel spanner.databaseOperations.get spanner.databaseOperations.list spanner.databases.create spanner.databases.get spanner.databases.list spanner.instancePartitions.get spanner.instancePartitions.list spanner.instances.createTagBinding spanner.instances.deleteTagBinding spanner.instances.get spanner.instances.list spanner.instances.listEffectiveTags spanner.instances.listTagBindings
Cloud Spanner Viewer (roles/spanner.viewer) A principal with this role can: View all Spanner instances (but cannot modify instances). View all Spanner databases (but cannot modify or read from databases). For example, you can combine this role with the roles/spanner.databaseUser role to grant a user with access to a specific database, but only view access to other instances and databases. This role is recommended at the Google Cloud project level for users interacting with Cloud Spanner resources in the Google Cloud console. Lowest-level resources where you can grant this role: Project	monitoring.timeSeries.list resourcemanager.projects.get resourcemanager.projects.list spanner.databases.list spanner.instanceConfigs.get spanner.instanceConfigs.list spanner.instancePartitions.get spanner.instancePartitions.list spanner.instances.get spanner.instances.list spanner.instances.listEffectiveTags spanner.instances.listTagBindings

Note: When the assigned role is spanner.databaseReader, requests for a read-only transaction might occasionally fail with a permissions error. To resolve this problem, see Manage the write-sessions fraction.

Basic roles

Basic roles are project-level roles that predate IAM. See Basic roles for additional details.

Although Spanner supports the following basic roles, you should use one of the predefined roles shown earlier whenever possible. Basic roles include broad permissions that apply to all of your Google Cloud resources; in contrast, Spanner's predefined roles include fine-grained permissions that apply only to Spanner.

Basic role	Description
roles/viewer	Can list and get the metadata of schemas and instances. Can also read and query using SQL on a database.
roles/editor	Can do all that a roles/viewer can do. Can also create instances and databases and write data into a database.
roles/owner	Can do all that a roles/editor can do. Can also modify access to databases and instances.

Custom roles

If the predefined roles for Spanner don't address your business requirements, you can define your own custom roles with permissions that you specify.

Before you create a custom role, you must identify the tasks that you need to perform. You can then identify the permissions that are required for each task and add these permissions to the custom role.

Custom roles for service account tasks

For most tasks, it's obvious which permissions you need to add to your custom role. For example, if you want your service account to be able to create a database, add the permission spanner.databases.create to your custom role.

However, when you're reading or writing data in a Spanner table, you need to add several different permissions to your custom role. The following table shows which permissions are required for reading and writing data.

Service account task	Required permissions
Read data	spanner.databases.select spanner.sessions.create spanner.sessions.delete
Insert, update, or delete data	spanner.databases.beginOrRollbackReadWriteTransaction spanner.databases.write spanner.sessions.create spanner.sessions.delete
Create a backup	spanner.backups.create spanner.databases.createBackup
Restore a database	spanner.databases.create spanner.backups.restoreDatabase

Custom roles for Google Cloud console tasks

To identify the list of permissions you need for a given task in the Google Cloud console, you determine the workflow for that task and compile the permissions for that workflow. For example, to view the data in a table, you would follow these steps in the Google Cloud console:

Step	Permissions
1. Access the project	resourcemanager.projects.get
2. View the list of instances	spanner.instances.list
3. Select an instance	spanner.instances.get
4. View the list of databases	spanner.databases.list
5. Select a database and a table	spanner.databases.getDdl
6. View data in a table	spanner.databases.select, spanner.sessions.create, spanner.sessions.delete

In this example, you need these permissions:

• resourcemanager.projects.get
• spanner.databases.getDdl
• spanner.databases.list
• spanner.databases.select
• spanner.instances.get
• spanner.instances.list
• spanner.sessions.create
• spanner.sessions.delete

The following table lists the permissions required for actions in the Google Cloud console.

Action	Permissions
View the list of instances on the Instances page	resourcemanager.projects.get spanner.instances.list
View the list on the Permissions tab of the Instance page	spanner.instances.getIamPolicy
Add principals on the Permissions tab of the Instance page	spanner.instances.setIamPolicy
Select an instance from the instance list to view the Instance Details page	spanner.instances.get
Create an instance	spanner.instanceConfigs.list spanner.instanceOperations.get spanner.instances.create
Delete an instance	spanner.instances.delete
Modify an instance	spanner.instanceOperations.get spanner.instances.update
Create a partition	spanner.instancePartitions.list spanner.instancePartitionOperations.get spanner.instancePartitions.create
Delete a partition	spanner.instancePartitions.delete
Modify a partition	spanner.instancePartitionOperations.get spanner.instancePartitions.update
View the graphs in the Monitor tab on the Instance details page or the Database details page	monitoring.metricDescriptors.get monitoring.metricDescriptors.list monitoring.timeSeries.list spanner.instances.get
View the list of databases on the Instance details page	spanner.databases.list
View the list on the Permissions tab of the Database details page	spanner.databases.getIamPolicy
Add principals on the Permissions tab of the Database details page	spanner.databases.setIamPolicy
Select a database from the database list and view the schema on the Database details page	spanner.databases.get spanner.databases.getDdl
Create a database	spanner.databases.create
Delete a database	spanner.databases.drop
Create a table Update a table schema	spanner.databaseOperations.get spanner.databaseOperations.list spanner.databases.updateDdl
View data in the Data tab of the Database details page Create and run a query	spanner.databases.select spanner.sessions.create spanner.sessions.delete
Modify data in a table	spanner.databases.beginOrRollbackReadWriteTransaction spanner.databases.select spanner.databases.write spanner.sessions.create spanner.sessions.delete
View the Backup/Restore page	spanner.backups.list spanner.backups.get
View the list of backup operations	spanner.backupOperations.list
View the list of restore operations	spanner.databaseOperations.list
Create a backup	spanner.backups.create spanner.databases.createBackup spanner.databases.list^1 spanner.backupOperations.list^1
Restore a database from a backup	spanner.instanceConfigs.list spanner.instances.get spanner.backups.get spanner.backups.restoreDatabase spanner.instances.list spanner.databases.create
Update a backup	spanner.backups.update
Delete a backup	spanner.backups.delete
Create a backup schedule	spanner.backupSchedules.create spanner.databases.createBackup
Update a backup schedule	spanner.backupSchedules.update
Delete a backup schedule	spanner.backupSchedules.delete

¹ Required if you are creating a backup from the Backup/Restore page at the instance level instead of the database level.

Spanner IAM policy management

You can get, set, and test IAM policies using the REST or RPC APIs on Spanner instance, database, and backup resources.

Instances

REST API	RPC API
projects.instances.getIamPolicy	GetIamPolicy
projects.instances.setIamPolicy	SetIamPolicy
projects.instances.testIamPermissions	TestIamPermissions

Databases

REST API	RPC API
projects.instances.databases.getIamPolicy	GetIamPolicy
projects.instances.databases.setIamPolicy	SetIamPolicy
projects.instances.databases.testIamPermissions	TestIamPermissions

Backups

REST API	RPC API
projects.instances.backups.getIamPolicy	GetIamPolicy
projects.instances.backups.setIamPolicy	SetIamPolicy
projects.instances.backups.testIamPermissions	TestIamPermissions

What's next

• Learn more about Identity and Access Management.
• Learn how to apply IAM roles for a Spanner database, instance, or Google Cloud project.
• Learn how to control access to Google Cloud resources, including Spanner, from the internet.