Access Control for Cloud Spanner

Overview

Google Cloud 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 makes it easy 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 Google Cloud 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 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.create Create a database.
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 operations.
spanner.databaseOperations.get Get a specific database operation.
spanner.databaseOperations.cancel Cancel a database operation.
spanner.databaseOperations.delete Delete a database 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.

Roles

Roles are a bundle of one or more permissions. For example, roles/spanner.databaseUser contains the permissions spanner.databases.read and spanner.database.write. There are two sets of role types 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 roles, including a list of the permissions associated with each role:

Role Permissions Description
roles/spanner.admin

(Person role)
resourcemanager.projects.get
spanner.databases.*
spanner.databaseOperations.*
spanner.instances.*
spanner.instanceConfigs.*
spanner.instanceOperations.*
spanner.sessions.*
Recommended to grant at the Google Cloud project level. Has complete access to all Cloud Spanner resources in a Google Cloud project. A principal with this role can:
  • Grant and revoke permissions to other principals 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.
roles/spanner.databaseAdmin

(Person role)
resourcemanager.projects.get
spanner.databases.*
spanner.databaseOperations.*
spanner.instances.list
spanner.instances.get
spanner.instances.getIamPolicy
spanner.instances.testIamPermissions
spanner.sessions.*
Recommended to grant at the Google Cloud project level. A principal with this role can:
  • Get/list all Cloud Spanner instances in project.
  • Create/list/drop databases in the instance on which it is granted.
  • Grant/revoke access to databases in the project.
  • Read from and write to all Cloud Spanner databases in the project.
roles/spanner.databaseReader

(Machine role)
spanner.databases.beginReadOnlyTransaction
spanner.databases.getDdl
spanner.databases.read
spanner.databases.select
spanner.sessions.create
spanner.sessions.delete
spanner.sessions.get
Recommended to grant at the database level. A principal with this role can:
  • Read from the Cloud Spanner database.
  • Execute SQL queries on the database.
  • View schema for the database.
roles/spanner.databaseUser

(Machine role)
spanner.databases.beginOrRollbackReadWriteTransaction
spanner.databases.beginReadOnlyTransaction
spanner.databases.getDdl
spanner.databases.read
spanner.databases.select
spanner.databases.updateDdl
spanner.databases.write
spanner.sessions.create
spanner.sessions.delete
spanner.sessions.get
Recommended to grant at the database level. A principal with this role can:
  • Read from and write to the Cloud Spanner database.
  • Execute SQL queries on the database.
  • View and update schema for the database.
roles/spanner.viewer

(Person role)
resourcemanager.projects.get
spanner.databases.list
spanner.instances.get
spanner.instances.list
Recommended to grant at the Google Cloud project level. A principal with this role can:
  • View all Cloud Spanner instances (but cannot modify instances).
  • View all Cloud Spanner databases (but cannot modify databases and cannot 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 required at the Google Cloud project level for users interacting with Cloud Spanner resources in the Google Cloud Platform Console.

Primitive roles

The following primitive roles are supported but not recommended. Prefer to use one of the roles in the table above instead. To learn more about primitive roles, which are project-level roles that predate Cloud IAM, see Primitive Roles.

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/writer 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/writer can do. Can also modify access to databases and instances.

Cloud Spanner IAM policy management

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

What's next

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Cloud Spanner Documentation