Access control guide

This page describes how you use Identity and Access Management (IAM) roles and permissions to control access to Cloud Logging data in Google Cloud resources.

Overview

IAM permissions and roles determine your ability to access logs data in the Logging API, the Logs Explorer, and the gcloud command-line tool.

A role is a collection of permissions. You can't grant a member permissions directly; instead, you grant them a role. When you grant a role to a member, you grant them all the permissions that the role contains. You can grant multiple roles to the same member.

To use Logging within a Google Cloud resource, such as a Google Cloud project, folder, bucket, or organization, you must have an IAM role that contains the appropriate permissions.

Predefined roles

IAM provides predefined roles to give granular access to specific Google Cloud resources and prevent unwanted access to other resources. Google Cloud creates and maintains these roles and automatically updates their permissions as necessary, such as when Logging adds new features.

The following table lists the Logging roles, the roles' titles, their descriptions, contained permissions, and the lowest-level resource type where the roles can be set. A particular role can be granted on this resource type or, in most cases, any type above it in the Google Cloud hierarchy.

To get a list of each individual permission contained in a role, see Getting the role metadata.

Role	Title	Description	Permissions	Lowest resource
`roles/logging.admin`	Logging Admin	Provides all permissions necessary to use all features of Cloud Logging.	logging.buckets.copyLogEntries logging.buckets.create logging.buckets.delete logging.buckets.get logging.buckets.list logging.buckets.undelete logging.buckets.update logging.cmekSettings.* logging.exclusions.* logging.fields.* logging.locations.* logging.logEntries.* logging.logMetrics.* logging.logServiceIndexes.* logging.logServices.* logging.logs.* logging.notificationRules.* logging.operations.* logging.privateLogEntries.* logging.queries.* logging.sinks.* logging.usage.* logging.views.* resourcemanager.projects.get resourcemanager.projects.list	Project
`roles/logging.bucketWriter`	Logs Bucket Writer	Ability to write logs to a log bucket.	logging.buckets.write	Bucket
`roles/logging.configWriter`	Logs Configuration Writer	Provides permissions to read and write the configurations of logs-based metrics and sinks for exporting logs.	logging.buckets.create logging.buckets.delete logging.buckets.get logging.buckets.list logging.buckets.undelete logging.buckets.update logging.cmekSettings.* logging.exclusions.* logging.locations.* logging.logMetrics.* logging.logServiceIndexes.* logging.logServices.* logging.logs.list logging.operations.* logging.sinks.* logging.views.create logging.views.delete logging.views.get logging.views.list logging.views.update resourcemanager.projects.get resourcemanager.projects.list	Project
`roles/logging.fieldAccessor`	Log Field Accessor ^Beta	Ability to read restricted fields in a log bucket.	logging.fields.*	Bucket
`roles/logging.logWriter`	Logs Writer	Provides the permissions to write log entries.	logging.logEntries.create	Project
`roles/logging.privateLogViewer`	Private Logs Viewer	Provides permissions of the Logs Viewer role and in addition, provides read-only access to log entries in private logs.	logging.buckets.get logging.buckets.list logging.exclusions.get logging.exclusions.list logging.locations.* logging.logEntries.list logging.logMetrics.get logging.logMetrics.list logging.logServiceIndexes.* logging.logServices.* logging.logs.list logging.privateLogEntries.* logging.queries.create logging.queries.delete logging.queries.get logging.queries.list logging.queries.listShared logging.queries.update logging.sinks.get logging.sinks.list logging.usage.* logging.views.access logging.views.get logging.views.list resourcemanager.projects.get	Project
`roles/logging.viewAccessor`	Logs View Accessor	Ability to read logs in a view.	logging.logEntries.download logging.views.access logging.views.listLogs logging.views.listResourceKeys logging.views.listResourceValues	Project
`roles/logging.viewer`	Logs Viewer	Provides access to view logs.	logging.buckets.get logging.buckets.list logging.exclusions.get logging.exclusions.list logging.locations.* logging.logEntries.list logging.logMetrics.get logging.logMetrics.list logging.logServiceIndexes.* logging.logServices.* logging.logs.list logging.operations.get logging.operations.list logging.queries.create logging.queries.delete logging.queries.get logging.queries.list logging.queries.listShared logging.queries.update logging.sinks.get logging.sinks.list logging.usage.* logging.views.get logging.views.list resourcemanager.projects.get	Project

Further considerations

When deciding which permissions and roles apply to your resource members' use cases, consider the following:

roles/logging.viewer (Logs Viewer) gives you read-only access to all features of Logging, except Access Transparency logs and Data Access audit logs.
roles/logging.privateLogViewer (Private Logs Viewer) includes roles/logging.viewer, plus the ability to read Access Transparency logs and Data Access audit logs. This role applies only to the _Required and _Default buckets.
roles/logging.logWriter (Logs Writer) can be granted to service accounts to give applications just enough permissions to write logs. This role doesn't grant viewing permissions.
roles/logging.bucketWriter (Logs Buckets Writer) can be granted to service accounts to give Cloud Logging just enough permissions to write logs to a log bucket. To restrict this role to a specific bucket, use an IAM condition; see Routing logs from one project to another bucket in a different project for an example.
roles/logging.configWriter (Logs Configuration Writer) gives you the permissions to create logs-based metrics, exclusions, buckets, and views, and to use sinks. To use the Logs Explorer (console) for these actions, add roles/logging.viewer.
roles/logging.admin (Logging Admin) grants you all permissions related to Logging.
roles/logging.viewAccessor (Logs View Accessor) gives you permissions to download logs, and to read logs, resource keys, and values in a log view. To restrict this role to a view in a specific bucket, use an IAM condition; see Reading logs from a bucket for an example.
roles/logging.fieldAccessor (Logs Field Accessor) gives you permissions to read logs, resource keys, and values for a subset of LogEntry fields for a given log bucket. See Field-level access control for details.
roles/viewer (Project Viewer) is the same as roles/logging.viewer. The role gives you read-only access to all Logging features except for Access Transparency logs and Data Access audit logs. This role applies only to the _Required and _Default buckets.
roles/editor (Project Editor) includes the permissions of roles/logging.viewer, plus permissions to write log entries, delete logs, and create logs-based metrics. The role doesn't let you create sinks or read Access Transparency logs or Data Access audit logs.
roles/owner (Project Owner) gives you full access to Logging, including Access Transparency logs and Data Access audit logs.

Granting roles

To learn how to grant a role to a member, see Granting, changing, and revoking access.

You can grant multiple roles to the same user. To get a list of the permissions contained in a role, see Getting the role metadata.

If you're trying to access a Google Cloud resource and lack the necessary permissions, contact the member who is listed as the Owner for the resource.

Custom roles

To create a custom role with Logging permissions, do the following:

For a role granting permissions for the Logging API, choose permissions from API permissions, then follow the instructions to create a custom role.
For a role granting permissions to use the Logs Explorer, choose from permission groups in Console permissions, then follow the instructions to create a custom role.
For a role granting permissions to use gcloud logging, see the Command-line permissions section on this page, then follow the instructions to create a custom role.

For more information on custom roles, see Understanding IAM custom roles.

API permissions

Logging API methods require specific IAM permissions. The following table lists the permissions needed by the API methods.

If you're interested in logs held in Google Cloud organizations, billing accounts, and folders, note that those resources have their own API methods for logs and sinks. Rather than repeating all the methods in the table, only the projects methods are shown individually.

Logging method	Required permission	Resource type
`billingAccounts.logs.*`	`logging.logs.` (See `projects.logs.`)	billing accounts
`billingAccounts.sinks.*`	`logging.sinks.` (See `projects.sinks.`.)	billing accounts
`billingAccounts.locations.buckets.*`	`logging.buckets.` (See `projects.locations.buckets.`.)	billing accounts
`entries.list`	`logging.logEntries.list` or `logging.privateLogEntries.list`	projects, organizations, folders, billing accounts
`entries.tail`	`logging.logEntries.list` or `logging.privateLogEntries.list`	projects, organizations, folders, billing accounts
`entries.write`	`logging.logEntries.create`	projects, organizations, folders, billing accounts
`folders.logs.*`	`logging.logs.` (See `projects.logs.`)	folders
`folders.sinks.*`	`logging.sinks.` (See `projects.sinks.`)	folders
`folders.locations.buckets.*`	`logging.buckets.` (See `projects.locations.buckets.`)	folders
`monitoredResourceDescriptors.list`	(none)	(none)
`organizations.logs.*`	`logging.logs.` (See `projects.logs.`)	organizations
`organizations.sinks.*`	`logging.sinks.` (See `projects.sinks.`)	organizations
`organizations.locations.buckets.*`	`logging.buckets.` (See `projects.locations.buckets.`)	organizations
`projects.exclusions.create`	`logging.exclusions.create`	projects
`projects.exclusions.delete`	`logging.exclusions.delete`	projects
`projects.exclusions.get`	`logging.exclusions.get`	projects
`projects.exclusions.list`	`logging.exclusions.list`	projects
`projects.exclusions.patch`	`logging.exclusions.update`	projects
`projects.logs.list`	`logging.logs.list`	projects
`projects.logs.delete`	`logging.logs.delete`	projects
`projects.sinks.list`	`logging.sinks.list`	projects
`projects.sinks.get`	`logging.sinks.get`	projects
`projects.sinks.create`	`logging.sinks.create`	projects
`projects.sinks.update`	`logging.sinks.update`	projects
`projects.sinks.delete`	`logging.sinks.delete`	projects
`projects.locations.buckets.list`	`logging.buckets.list`	projects
`projects.locations.buckets.get`	`logging.buckets.get`	projects
`projects.locations.buckets.patch`	`logging.buckets.update`	projects
`projects.locations.buckets.create`	`logging.buckets.create`	projects
`projects.locations.buckets.delete`	`logging.buckets.delete`	projects
`projects.locations.buckets.undelete`	`logging.buckets.undelete`	projects
`projects.metrics.list`	`logging.logMetrics.list`	projects
`projects.metrics.get`	`logging.logMetrics.get`	projects
`projects.metrics.create`	`logging.logMetrics.create`	projects
`projects.metrics.update`	`logging.logMetrics.update`	projects
`projects.metrics.delete`	`logging.logMetrics.delete`	projects

Console permissions

The following table lists the permissions needed to use the Logs Explorer.

In the table, a.b.{x,y} means a.b.x and a.b.y.

Console activity	Required permissions
Minimal read-only access	`logging.logEntries.list` `logging.logs.list` `logging.logServiceIndexes.list` `logging.logServices.list` `resourcemanager.projects.get`
Add ability to view Data Access audit logs	Add `logging.privateLogEntries.list`
Add ability to view Access Transparency logs	Add `logging.privateLogEntries.list`
Add ability to view logs-based metrics	Add `logging.logMetrics.`{`list`, `get`}
Add ability to view sinks	Add `logging.sinks.`{`list`, `get`}
Add ability to view logs usage	Add `logging.usage.get`
Add ability to exclude logs	Add `logging.exclusions.`{`list`, `create`, `get`, `update`, `delete`}
Add ability to use sinks	Add `logging.sinks.{list`, `create`, `get`, `update`, `delete`}
Add ability to create logs-based metrics	Add `logging.logMetrics.`{`list`, `create`, `get`, `update`, `delete`}

Command-line permissions

gcloud logging commands are controlled by IAM permissions.

To use any of the gcloud logging commands, you must have the serviceusage.services.use permission.

You must also have the IAM role that corresponds to the log's resource, and to your use case. For details, go to command-line interface permissions.

Access to exported logs

To create a sink to route logs, you must have one of the following roles, or a role with equivalent permissions: roles/logging.configWriter or roles/logging.admin or roles/owner.

After your log entries have been routed to a destination, access to the log copies is controlled entirely by IAM permissions and roles on the destinations: Cloud Storage, BigQuery, or Pub/Sub.

When creating a custom role that includes permissions to manage exclusion filters, add the logging.sinks.* permissions to the role instead of adding the logging.exclusions.* permissions. Managing exclusions is part of log sinks, so all permissions related to managing sinks, including setting exclusions, are included in the logging.sinks.* permissions.

Logging access scopes

Access scopes are the legacy method of specifying permissions for the service accounts on your Compute Engine VM instances.

The following access scopes apply to the Logging API:

Access scope	Permissions granted
https://www.googleapis.com/auth/logging.read	`roles/logging.viewer`
https://www.googleapis.com/auth/logging.write	`roles/logging.logWriter`
https://www.googleapis.com/auth/logging.admin	Full access to the Logging API.
https://www.googleapis.com/auth/cloud-platform	Full access to the Logging API and to all other enabled Google Cloud APIs.

For information on using this legacy method to set your service accounts' levels of access, see Service account permissions.