Access control for Cloud Spanner

Overview

Identity and Access Management (IAM) allows you to control user and group access to Cloud Spanner resources at the project, Cloud Spanner instance, and Cloud 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 Cloud Spanner IAM allows you to grant a permission to a user or group without having to modify each Cloud Spanner instance or database permission individually.

This document focuses on the IAM permissions relevant to Cloud 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 Cloud Spanner resources. For example, the spanner.databases.read permission allows a user to read from a database using Cloud 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 Cloud Spanner.

Instance configurations

The following permissions apply to Cloud Spanner instance configurations (see the instance configuration reference: REST, RPC).

Instance configuration permission name Description
spanner.instanceConfigs.list List the set of instance configurations.
spanner.instanceConfigs.get Get an instance configuration.

Instances

The following permissions apply to Cloud Spanner instances (see the instance reference: REST, RPC).

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 Cloud Spanner instance operations (see the instance reference: REST, RPC).

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.

Databases

The following permissions apply to Cloud Spanner databases (see the database reference: REST, RPC).

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.

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 Cloud Spanner database.
spanner.databases.beginOrRollbackReadWriteTransaction Begin or roll back a read-write transaction on a Cloud 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.

Database operations

The following permissions apply to Cloud Spanner database operations (see the database reference: REST, RPC).

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.
spanner.databaseOperations.delete

Delete a database operation.

Backups

The following permissions apply to Cloud Spanner backups (see the backups reference: REST, RPC).

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 Cloud Spanner backup operations (see the database reference: REST, RPC).

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.

Sessions

The following permissions apply to Cloud Spanner sessions (see the database reference: REST, RPC).

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.database.write. There are two types of predefined roles for Cloud 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.

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

Role Title Description Permissions Lowest resource
roles/spanner.admin Cloud Spanner Admin

Has complete access to all Cloud Spanner resources in a Google Cloud project. A member with this role can:

  • Grant and revoke permissions to other members for all Cloud Spanner resources in the project.
  • Allocate and delete chargeable Cloud 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.
  • monitoring.timeSeries.list
  • resourcemanager.projects.get
  • resourcemanager.projects.list
  • spanner.*
Project
roles/spanner.backupAdmin Cloud Spanner Backup Admin

A member with this role can:

  • Create, view, update, and delete backups.
  • View and manage a backup's IAM policy.

This role cannot restore a database from a backup.

  • monitoring.timeSeries.list
  • resourcemanager.projects.get
  • resourcemanager.projects.list
  • spanner.backupOperations.*
  • 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.instances.get
  • spanner.instances.list
Instance
roles/spanner.backupWriter Cloud Spanner Backup Writer This role is intended to be used by scripts that automate backup creation. A member with this role can create backups, but cannot update or delete them.
  • spanner.backupOperations.get
  • spanner.backupOperations.list
  • spanner.backups.create
  • spanner.backups.get
  • spanner.backups.list
  • spanner.databases.createBackup
  • spanner.databases.get
  • spanner.databases.list
  • spanner.instances.get
Instance
roles/spanner.databaseAdmin Cloud Spanner Database Admin

A member with this role can:

  • Get/list all Cloud 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.
  • monitoring.timeSeries.list
  • resourcemanager.projects.get
  • resourcemanager.projects.list
  • spanner.databaseOperations.*
  • spanner.databases.beginOrRollbackReadWriteTransaction
  • spanner.databases.beginPartitionedDmlTransaction
  • spanner.databases.beginReadOnlyTransaction
  • 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.write
  • spanner.instances.get
  • spanner.instances.getIamPolicy
  • spanner.instances.list
  • spanner.sessions.*
Instance
roles/spanner.databaseReader Cloud Spanner Database Reader

A member with this role can:

  • Read from the Cloud Spanner database.
  • Execute SQL queries on the database.
  • View schema for the database.
  • spanner.databases.beginReadOnlyTransaction
  • spanner.databases.getDdl
  • spanner.databases.partitionQuery
  • spanner.databases.partitionRead
  • spanner.databases.read
  • spanner.databases.select
  • spanner.instances.get
  • spanner.sessions.*
Database
roles/spanner.databaseUser Cloud Spanner Database User

A member with this role can:

  • Read from and write to the Cloud Spanner database.
  • Execute SQL queries on the database, including DML and Partitioned DML.
  • View and update schema for the database.
  • spanner.databaseOperations.*
  • spanner.databases.beginOrRollbackReadWriteTransaction
  • spanner.databases.beginPartitionedDmlTransaction
  • spanner.databases.beginReadOnlyTransaction
  • spanner.databases.getDdl
  • spanner.databases.partitionQuery
  • spanner.databases.partitionRead
  • spanner.databases.read
  • spanner.databases.select
  • spanner.databases.updateDdl
  • spanner.databases.write
  • spanner.instances.get
  • spanner.sessions.*
Database
roles/spanner.restoreAdmin Cloud Spanner Restore Admin

A member 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.

  • monitoring.timeSeries.list
  • resourcemanager.projects.get
  • resourcemanager.projects.list
  • spanner.backups.get
  • spanner.backups.list
  • spanner.backups.restoreDatabase
  • spanner.databaseOperations.cancel
  • spanner.databaseOperations.get
  • spanner.databaseOperations.list
  • spanner.databases.create
  • spanner.databases.get
  • spanner.databases.list
  • spanner.instances.get
  • spanner.instances.list
Instance
roles/spanner.viewer Cloud Spanner Viewer

A member with this role can:

  • View all Cloud Spanner instances (but cannot modify instances).
  • View all Cloud 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.

  • monitoring.timeSeries.list
  • resourcemanager.projects.get
  • resourcemanager.projects.list
  • spanner.databases.list
  • spanner.instanceConfigs.*
  • spanner.instances.get
  • spanner.instances.list
Project

Primitive roles

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

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

Primitive 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 Cloud Spanner do not 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 Cloud 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 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 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.get, 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.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 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 members 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

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 members 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 tab

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.list1
spanner.backupOperations.list1

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

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

Cloud Spanner IAM policy management

You can get, set, and test IAM policies using the REST or RPC APIs on Cloud 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