This document describes how you use Identity and Access Management (IAM) roles and permissions to control access to logs data in the Logging API, the Logs Explorer, and the Google Cloud CLI.
Overview
IAM permissions and roles determine your ability to access logs data in the Logging API, the Logs Explorer, and the Google Cloud CLI.
A role is a collection of permissions. You can't grant a principal permissions directly; instead, you grant them a role. When you grant a role to a principal, you grant them all the permissions that the role contains. You can grant multiple roles to the same principal.
To use Logging within a Google Cloud resource, such as a Google Cloud project, folder, bucket, or organization, a principal must have an IAM role that contains the appropriate permissions.
Predefined roles
IAM provides predefined roles to grant 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 predefined roles for Logging. For each role, the table displays the role title, description, contained permissions, and the lowest-level resource type where the roles can be granted. You can grant the predefined roles at the Google Cloud project level or, in most cases, any type higher in the resource hierarchy. To restrict the Logs View Accessor role to a log view on a bucket, use resource attributes for IAM Conditions.
To get a list of all individual permissions contained in a role, see Getting the role metadata.
Role | Permissions |
---|---|
Logging Admin( Provides all permissions necessary to use all features of Cloud Logging. Lowest-level resources where you can grant this role:
|
|
Logs Bucket Writer( Ability to write logs to a log bucket. Lowest-level resources where you can grant this role:
|
|
Logs Configuration Writer( Provides permissions to read and write the configurations of logs-based metrics and sinks for exporting logs. Lowest-level resources where you can grant this role:
|
|
Log Field Accessor( Ability to read restricted fields in a log bucket. Lowest-level resources where you can grant this role:
|
|
Log Link Accessor( Ability to see links for a bucket. |
|
Logs Writer( Provides the permissions to write log entries. Lowest-level resources where you can grant this role:
|
|
Private Logs Viewer( Provides permissions of the Logs Viewer role and in addition, provides read-only access to log entries in private logs. Lowest-level resources where you can grant this role:
|
|
Logs View Accessor( Ability to read logs in a view. Lowest-level resources where you can grant this role:
|
|
Logs Viewer( Provides access to view logs. Lowest-level resources where you can grant this role:
|
|
The following sections provide additional information to help you decide which roles apply to your principals' use cases.
Logging roles
To let a user perform all actions in Logging, grant the Logging Admin (
roles/logging.admin
) role.To let a user create and modify logging configurations, grant the Logs Configuration Writer (
roles/logging.configWriter
) role. This role lets you create or modify any of the following:This role isn't sufficient to create log-based metrics or log-based alerting policies. For information about the roles required for these tasks, see Permissions for log-based metrics and Permissions for log-based alerting policies.
To let a user read logs in the
_Required
and_Default
buckets or to use the Logs Explorer and Log Analytics pages, grant one of the following roles:- For access to all logs in the
_Required
bucket, and access to the_Default
view on the_Default
bucket, grant the Logs Viewer (roles/logging.viewer
) role. - For access to all logs in the
_Required
and_Default
buckets, including data access logs, grant the Private Logs Viewer (roles/logging.privateLogViewer
) role.
- For access to all logs in the
To let a user read logs in all log views that are in a project, grant them the IAM role of
roles/logging.viewAccessor
on the project.To let a user only read logs in a specific log view, you have two options:
Create an IAM policy for the log view, and then add an IAM binding to that policy which grants the principal access to the log view.
Grant the principal the IAM role of
roles/logging.viewAccessor
on the project that contains the log view, but attach an IAM condition to restrict the grant to the specific log view.
For information about creating log views and granting access, see Configure log views on a log bucket.
To give a user access to restricted
LogEntry
fields, if any, in a given log bucket, grant the Logs Field Accessor (roles/logging.fieldAccessor
) role. For more information, see Configure field-level access.To let a user write logs by using the Logging API, grant the Logs Writer (
roles/logging.logWriter
) role. This role doesn't grant viewing permissions.To let the service account of a sink route logs to a bucket in a different Google Cloud project, grant the service account the Logs Bucket Writer (
roles/logging.bucketWriter
) role. For instructions about granting permissions to a service account, see Set destination permissions.
Project-level roles
To give view access to most Google Cloud services, grant the Viewer (
roles/viewer
) role.This role includes all permissions granted by the Logs Viewer (
roles/logging.viewer
) role.To give editor access to most Google Cloud services, grant the Editor (
roles/editor
) role.This role includes all permissions granted by the Logs Viewer (
roles/logging.viewer
) role, and the permissions to write log entries, delete logs, and create log-based metrics. However, this role doesn't let users create sinks, read Data Access audit logs that are in the_Default
bucket, or read logs that are in user-defined log buckets.To give full access to most Google Cloud services, grant the Owner (
roles/owner
) role.
Granting roles
To learn how to grant a role to a principal, 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, then contact the principal 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 about custom roles, see Understanding IAM custom roles.
Permissions for the Google Cloud console
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 |
View Data Access audit log | logging.privateLogEntries.list |
View log-based metrics | logging.logMetrics.[list, get] |
View sinks | logging.sinks.[list, get] |
View logs usage | logging.usage.get |
List and view log scopes | logging.logScopes.[get, list] |
View default log scope | observability.scopes.get |
Exclude logs | logging.exclusions.[list, create, get, update, delete] |
Create and use sinks | logging.sinks.[list, create, get, update, delete] |
Create log-based metrics | logging.logMetrics.[list, create, get, update, delete] |
Save and use private queries | logging.queries.[list, create, get, update, delete] |
Save and use shared queries | logging.queries.[share, getShared, updateShared, deleteShared,
listShared] |
Use recent queries | logging.queries.[create, list] |
Create and manage log scopes | logging.logScopes.[create, delete, get, list, update] |
Set and manage default log scope | observability.scopes.[get, update] |
Permissions for the command-line
gcloud logging
commands are
controlled by IAM permissions.
To use any of the gcloud logging
commands, principals must have the
serviceusage.services.use
permission.
A principal must also have the IAM role that corresponds to the log's resource, and to the use case. For details, see command-line interface permissions.
Permissions for linked BigQuery datasets
The following list describes the predefined roles and corresponding permissions for managing your linked BigQuery datasets:
The Logging Admin (
roles/logging.admin
) and Logs Configuration Writer (roles/logging.configWriter
) roles contain the following permissions:logging.links.list
logging.links.create
logging.links.get
logging.links.delete
The Log Link Accessor (
roles/logging.linkViewer
), Private Logs Viewer (roles/logging.privateLogViewer
), and Logs Viewer (roles/logging.viewer
) roles contain the following permissions:logging.links.list
logging.links.get
The previously listed roles and permissions only apply to using Cloud Logging to manage your linked datasets. If you use the BigQuery interface to manage your datasets, you might need separate BigQuery roles and permissions. See Access control with IAM for BigQuery for more information.
Permissions for saving queries
This section describes the predefined roles and the permissions for saving, sharing, and using queries in the Logs Explorer and Log Analytics pages. Using private saved queries that are only visible to you, and using saved queries that are shared with other members of the Google Cloud project require different permissions:
-
To get the permissions that you need to use private saved queries, ask your administrator to grant you the Logs Viewer (
roles/logging.viewer
) IAM role on your project.This predefined role contains the permissions required to use private saved queries. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
The following permissions are required to use private saved queries:
-
logging.queries.list
-
logging.queries.create
-
logging.queries.get
-
logging.queries.update
-
logging.queries.delete
-
-
To get the permissions that you need to create, update, and delete shared queries, ask your administrator to grant you the Logging Admin (
roles/logging.admin
) IAM role on your project.This predefined role contains the permissions required to create, update, and delete shared queries. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
The following permissions are required to create, update, and delete shared queries:
-
logging.queries.share
-
logging.queries.updateShared
-
logging.queries.deleteShared
-
-
To get the permissions that you need to list and get shared queries, ask your administrator to grant you the Logs Viewer (
roles/logging.viewer
) IAM role on your project.This predefined role contains the permissions required to list and get shared queries. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
The following permissions are required to list and get shared queries:
-
logging.queries.listShared
-
logging.queries.getShared
-
Permissions for routing logs
For information about setting access controls when creating and managing sinks to route logs, see Set destination permissions.
Note that managing exclusion filters is integrated with configuring sinks. All
permissions related to managing sinks, including setting exclusion filters, are
included in the logging.sinks.*
permissions. 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.
After your log entries have been routed to a supported destination, access to the log copies is controlled entirely by IAM permissions and roles on the destinations: Cloud Storage, BigQuery, or Pub/Sub.
Permissions for log-based metrics
Following is a summary of the common roles and permissions that a principal needs to access log-based metrics:
The Logs Configuration Writer (
roles/logging.configWriter
) role lets principals list, create, get, update, and delete log-based metrics.The Logs Viewer (
roles/logging.viewer
) role contains permissions to view existing metrics. Specifically, a principal needs thelogging.logMetrics.get
andlogging.logMetrics.list
permissions to view existing metrics.The Monitoring Viewer (
roles/monitoring.viewer
) role contains the permissions to read TimeSeries data. Specifically, a principal needs themonitoring.timeSeries.list
permission to read time series data.The Logging Admin (
roles/logging.admin
), Project Editor (roles/editor
), and Project Owner (roles/owner
) roles contain the permissions to create log-based metrics. Specifically, a principal needs thelogging.logMetrics.create
permission to create log-based metrics.
Permissions for log-based alerting policies
To create and manage log-based alerting policies, a principal needs the following Logging and Monitoring roles and permissions:
-
To get the permissions that you need to read logs and to manage Logging notification rules, ask your administrator to grant you the Logging Admin (
roles/logging.admin
) IAM role on your project.This predefined role contains the permissions required to read logs and to manage Logging notification rules. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
The following permissions are required to read logs and to manage Logging notification rules:
-
logging.queries.listShared
-
logging.queries.getShared
-
-
To get the permissions that you need to manage log-based alerting policies and their notification channels, ask your administrator to grant you the following IAM roles on your project:
-
Monitoring AlertPolicy Editor (
roles/monitoring.alertPolicyEditor
) -
Monitoring NotificationChannel Editor (
roles/monitoring.notificationChannelEditor
)
These predefined roles contain the permissions required to manage log-based alerting policies and their notification channels. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
The following permissions are required to manage log-based alerting policies and their notification channels:
-
logging.queries.listShared
-
logging.queries.getShared
-
Monitoring AlertPolicy Editor (
-
To get the permissions that you need to create an alerting policy in the Google Cloud CLI, ask your administrator to grant you the Service Usage Consumer (
roles/serviceusage.serviceUsageConsumer
) IAM role on your project.This predefined role contains the permissions required to create an alerting policy in the Google Cloud CLI. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
The following permissions are required to create an alerting policy in the Google Cloud CLI:
-
logging.queries.listShared
-
logging.queries.getShared
-
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.