Access control

This page describes the access control options that are available to you in Cloud Bigtable.

Overview

Bigtable uses Identity and Access Management (IAM) for access control.

For Bigtable, you can configure access control at the project, instance, and table levels. Here are some examples of using access control at the project level:

• Allow a user to read from, but not write to, any table within the project.
• Allow a user to read from and write to any table within the project, but not manage instances.
• Allow a user to read from and write to any table within the project, and manage instances.

Here are some examples of using access control at the instance level:

• Allow a user to read from any table in only one instance in a project that has multiple instances.
• Allow a user to manage only one instance in a project that has multiple instances.

Examples of using access control at the table level include the following:

• Allow a user to write to a table but not read from the table.
• Allow a user to read from a table but not write to the table.

For a detailed description of IAM and its features, see the IAM developer's guide. In particular, see Granting, Changing, and Revoking Access to Project Members.

In Bigtable, you cannot grant access to the following types of members:

• allAuthenticatedUsers
• allUsers

For lists of the permissions and roles that Bigtable supports, see the following sections.

Enabling the Bigtable API

To view and assign Bigtable IAM roles, you must enable the Bigtable API for your project. You will not be able to see the Bigtable roles in the Cloud Console until you enable the API.

Enable the API

Permissions

This section summarizes the permissions that Bigtable supports.

Permissions allow users to perform specific actions on Bigtable resources. For example, the bigtable.instances.list permissions allows users to list all of the Bigtable instances within a project. You don't grant permissions to users directly; instead, you assign each user a predefined role or custom role, which grants one or more permissions.

The following tables list the IAM permissions that are associated with Bigtable:

Location permission name	Description
bigtable.locations.list	List Bigtable locations.

Instance permission name	Description
bigtable.instances.create	Create a Bigtable instance.
bigtable.instances.delete	Delete a Bigtable instance.
bigtable.instances.get	Get information about a Bigtable instance.
bigtable.instances.getIamPolicy	Read instance access control lists (ACLs). Returned as IAM policies.
bigtable.instances.list	List a project's Bigtable instances.
bigtable.instances.setIamPolicy	Update ACLs.
bigtable.instances.update	Update the settings for a Bigtable instance.

App profile permission name	Description
bigtable.appProfiles.create	Create a Bigtable app profile.
bigtable.appProfiles.delete	Delete a Bigtable app profile.
bigtable.appProfiles.get	Get information about a Bigtable app profile.
bigtable.appProfiles.list	List an instance's Bigtable app profiles.
bigtable.appProfiles.update	Update the settings for a Bigtable app profile.

Backups permission name	Description
bigtable.backups.create	Create a Bigtable backup.
bigtable.backups.get	Get a Bigtable backup.
bigtable.backups.list	List Bigtable backups.
bigtable.backups.delete	Delete a Bigtable backup.
bigtable.backups.update	Modify the expiration of a Bigtable backup.
bigtable.backups.restore	Restore a Bigtable backup.

Cluster permission name	Description
bigtable.clusters.create	Create a Bigtable cluster.
bigtable.clusters.delete	Delete a Bigtable cluster.
bigtable.clusters.get	Get information about a Bigtable cluster.
bigtable.clusters.list	List an instance's Bigtable clusters.
bigtable.clusters.update	Update the settings for a Bigtable cluster.

Table permission name	Description
bigtable.tables.checkConsistency	Check if a replicated table is up to date.
bigtable.tables.create	Create a table.
bigtable.tables.delete	Delete a table.
bigtable.tables.generateConsistencyToken	Generate token to check if a replicated table is up to date.
bigtable.tables.get	Get information about a table, including column families and their individual settings.
bigtable.tables.getIamPolicy	Read table ACLs. Returned as IAM policies.
bigtable.tables.list	List tables in an instance.
bigtable.tables.mutateRows	Modify rows within a table, or truncate the table.
bigtable.tables.readRows	Read rows from a table.
bigtable.tables.sampleRowKeys	Get a sample of the row keys that are used in a table.
bigtable.tables.setIamPolicy	Update table ACLs.
bigtable.tables.update	Update the settings for a table, including column families and their individual settings.

The following table lists the IAM permissions that are associated with Key Visualizer:

Key Visualizer permission name	Description
bigtable.keyvisualizer.get	Get Key Visualizer information about a table, including metadata about access patterns and row key distributions.
bigtable.keyvisualizer.list	List available Key Visualizer information for a table.

Predefined roles

Each predefined role is a bundle of one or more permissions. For example, roles/bigtable.reader provides read-only access to information about Bigtable instances, clusters, tables, and column families, as well as the data contained within your tables. You assign roles to users or groups, which allows them to perform actions on the resources in your project.

The following table lists the predefined roles for Bigtable, including a list of the permissions associated with each role:

Role	Permissions	Description
roles/bigtable.admin	Access to all Bigtable features: bigtable.*.* View access to monitoring graphs in the Cloud Console: monitoring.metricDescriptors.get monitoring.metricDescriptors.list monitoring.timeSeries.list Access to project-level metadata: resourcemanager.projects.get	Administers all instances within a project, including the data stored within tables. Can create new instances. Intended for project administrators. This includes access to Key Visualizer.
roles/bigtable.user	Read-only access to metadata for instances, clusters, tables, and column families: bigtable.*.get bigtable.*.list bigtable.tables.checkConsistency bigtable.tables.generateConsistencyToken Read-write access to tables: bigtable.tables.mutateRows bigtable.tables.readRows bigtable.tables.sampleRowKeys View access to monitoring graphs in the Cloud Console: monitoring.metricDescriptors.get monitoring.metricDescriptors.list monitoring.timeSeries.list Access to project-level metadata: resourcemanager.projects.get	Provides read-write access to the data stored within tables. Intended for application developers or service accounts. This includes access to Key Visualizer.
roles/bigtable.reader	Read-only access to metadata for instances, clusters, tables, and column families: bigtable.*.get bigtable.*.list bigtable.tables.checkConsistency bigtable.tables.generateConsistencyToken Read-only access to tables: bigtable.tables.readRows bigtable.tables.sampleRowKeys View access to monitoring graphs in the Cloud Console: monitoring.metricDescriptors.get monitoring.metricDescriptors.list monitoring.timeSeries.list Access to project-level metadata: resourcemanager.projects.get	Provides read-only access to the data stored within tables. Intended for data scientists, dashboard generators, and other data-analysis scenarios. This includes access to Key Visualizer.
roles/bigtable.viewer	Read-only access to metadata for instances, clusters, tables, and column families: bigtable.appProfiles.get bigtable.appProfiles.list bigtable.clusters.get bigtable.clusters.list bigtable.instances.get bigtable.instances.list bigtable.locations.list bigtable.tables.checkConsistency bigtable.tables.generateConsistencyToken bigtable.tables.get bigtable.tables.list View access to monitoring graphs in the Cloud Console: monitoring.metricDescriptors.get monitoring.metricDescriptors.list monitoring.timeSeries.list Access to project-level metadata: resourcemanager.projects.get	Provides no data access. Intended as a minimal set of permissions to access the Cloud Console for Bigtable. This does not include access to Key Visualizer.

Custom roles

If the predefined roles for Bigtable do not address your business requirements, you can define your own custom roles with permissions that you specify.

If your custom role needs to support access to the Cloud Console, you must identify the tasks that users will perform, then ensure that the custom role has the required permissions for each task, as shown in the table below. If a custom role does not have all of the required permissions for a task, and a user tries to perform that task, the Cloud Console will not work correctly.

Cloud Console task	Required permissions
Basic access to the Cloud Console	bigtable.appProfiles.get bigtable.appProfiles.list bigtable.clusters.get bigtable.clusters.list bigtable.instances.get bigtable.instances.list bigtable.locations.list resourcemanager.projects.get
Create an instance or cluster	Basic access permissions, plus: bigtable.clusters.create bigtable.instances.create
Modify an instance or cluster	Basic access permissions, plus: bigtable.clusters.update bigtable.instances.update
Manage replication configuration	Basic access permissions, plus: bigtable.appProfiles.create bigtable.appProfiles.delete bigtable.appProfiles.update
Delete an instance or cluster	Basic access permissions, plus: bigtable.clusters.delete bigtable.instances.delete
Monitor an instance by viewing graphs	Basic access permissions, plus: monitoring.metricDescriptors.get monitoring.metricDescriptors.list monitoring.timeSeries.list

Project-level IAM management

At the project level, you can grant, change, and revoke IAM roles using the Google Cloud Console, the IAM API, or the gcloud command-line tool. See Granting, Changing, and Revoking Access to Project Members for detailed instructions.

Instance-level IAM management

This section explains how to manage Bigtable IAM roles at the instance level.

Before you begin

Before you set instance-level IAM roles for a user, ensure that the user has at least one of the following project-level IAM roles:

• Bigtable Viewer (recommended)
• Bigtable Reader
• Bigtable User
• Bigtable Administrator

Note: You do not need to grant these project-level roles to service accounts because service accounts are associated with a Google Cloud project as opposed to a specific user.

Choose a project-level role that has no more permissions than the user actually needs across all instances in the project. For this reason, you should grant the Bigtable Viewer role in almost all cases.

If the user does not have at least one of these project-level roles, the user will not have access to Bigtable through the Cloud Console. The Cloud Console requires one of these project-level roles so that it can retrieve information about instances and clusters on behalf of the user.

Granting instance-level IAM roles

At the instance level, you can grant any of Bigtable's predefined roles to a user or service account. You can also grant any custom roles that you have defined.

Note: After you change a user's instance-level roles, it may take up to 2 minutes for the changes to take effect.

To grant a predefined or custom role to a user or service account at the instance level:

Console

1. Go to the Bigtable instances page in the Cloud Console.

   Go to the instances page

2. Check the boxes next to the instances whose roles you want to manage. An information panel appears.

3. In the information panel, click Permissions.

4. Under Add members, start typing the email address of the user or service account you want to add, then click the email address of the user or service account.

5. Click the Select a role drop-down list, then click Bigtable to select a predefined role or Custom to select a custom role.

6. Click the name of each role that you want to assign.

7. Click Add. The user or service account is granted the roles that you specified at the instance level.

gcloud

1. If you don't know the instance ID, use the bigtable instances list command to view a list of your project's instances:

   gcloud bigtable instances list
   

2. Use the bigtable instances set-iam-policy command:

   gcloud bigtable instances set-iam-policy INSTANCE_ID POLICY_FILE
   

   Provide the following:

   • INSTANCE_ID: The permanent identifier for the instance.
   • POLICY_FILE: Path to a local JSON or YAML file containing a valid IAM policy.

Table-level IAM management

This section explains how to manage Bigtable IAM roles at the table level.

Before you begin

Before you set table-level IAM roles for a user, ensure that the user has at least one of the following project-level IAM roles:

• Bigtable Viewer (recommended)
• Bigtable Reader
• Bigtable User
• Bigtable Administrator

Note: You do not need to grant these project-level roles to service accounts because service accounts are associated with a Google Cloud project as opposed to a specific user.

Choose a project-level role that has no more permissions than the user actually needs. For this reason, you should grant the Bigtable Viewer role in almost all cases.

If the user does not have at least one of these project-level roles, the user does not have access to Bigtable through the Cloud Console. The Cloud Console requires one of these project-level roles so that it can retrieve information about instances, clusters, and tables.

Granting table-level IAM roles

At the table level, you can grant any of Bigtable's predefined roles to a user or service account. You can also grant any custom roles that you have defined.

Note: After you change a user's table-level roles, it can take up to 2 minutes for the changes to take effect.

To grant a predefined or custom role to a user or service account at the table level:

Console

1. Go to the Bigtable instances page in the Cloud Console.

   Go to the instances page

2. Click the name of the instance that contains the table whose IAM you are setting.

3. Select Tables in the left navigation pane.

4. Check the boxes next to the tables whose roles you want to manage. An information panel appears.

5. In the information panel, click Permissions.

6. Under Add members, start typing the email address of the user or service account you want to add, then click the email address of the user or service account.

7. Click the Select a role drop-down list, then click Bigtable to select a predefined role or Custom to select a custom role.

8. Click the name of each role that you want to assign.

9. Click Add. The user or service account is granted the roles that you specified at the table level.

gcloud

1. If you don't know the instance ID, use the bigtable instances list command to view a list of your project's instances:

   gcloud bigtable instances list
   

2. If you don't know the instance's cluster IDs, use the bigtable clusters list command to view a list of clusters in the instance:

   gcloud bigtable clusters list --instances=INSTANCE_ID
   

3. Use the bigtable instances tables set-iam-policy command:

   gcloud bigtable instances tables set-iam-policy TABLE_ID \
       --instance=INSTANCE_ID POLICY_FILE
   

   Provide the following:

   • INSTANCE_ID: The permanent identifier for the instance.
   • POLICY_FILE: Path to a local JSON or YAML file containing a valid IAM policy.

IAM conditions

IAM Conditions let you define and enforce conditional, attribute-based access control for some Google Cloud resources, including Bigtable resources.

In Bigtable, you can enforce conditional access based on the following attributes:

• Date/time attributes: Use to set temporary (expiring), scheduled, or limited-duration access to Bigtable resources. For example, you can allow a user to access a table until a specified date.
• Resource attributes: Use to configure conditional access based on a resource name, resource type, or resource service attributes. In Bigtable, you can use attributes of instances, clusters, and tables to configure conditional access. For example, you can allow a user to manage tables only on tables that begin with a specific prefix, or you can allow a user to access only a specific table.

For more information about IAM Conditions, see the Conditions overview.

What's next

Learn more about IAM.