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 Cloud project level or, in most cases, any type higher in the Google Cloud hierarchy. To scope the Logs Buckets Writer or Logs View Accessor roles more tightly to the bucket level, you use resource attributes for IAM Conditions.
To get a list of each individual permission 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:
|
|
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:
|
|
Further considerations
When deciding which permissions and roles apply to your principals' use cases, consider the following:
roles/logging.admin
(Logging Admin) grants you all permissions related to Logging.roles/logging.viewer
(Logs Viewer) grants principals read-only access to most features of Logging.The Logs Viewer role grants principals access to both the
_AllLogs
log view in the_Required
bucket and the_Default
log view in the_Default
bucket.The Logs Viewer role doesn't let principals read the Data Access audit logs that are in the
_Default
bucket. To read these Data Access audit logs, principals need the Private Logs Viewer role (roles/logging.privateLogViewer
) for the appropriate log view.The Logs Viewer role doesn't let principals read logs that are stored in user-defined buckets; to read logs in user-defined buckets, principals need the Logs View Accessor role (
roles/logging.viewAccessor
) for the appropriate log view.roles/logging.privateLogViewer
(Private Logs Viewer) includes all the permissions contained byroles/logging.viewer
, plus the ability to read Data Access audit logs in the_Default
bucket.The Private Logs Viewer role doesn't let principals read Data Access audit logs if they are stored in user-defined buckets; to read these logs in user-defined buckets, principals need the Logs View Accessor role (
roles/logging.viewAccessor
) for the appropriate log view.roles/logging.viewAccessor
(Logs View Accessor) grants principals permissions to read logs, resource keys, and values using a log view and to download logs. 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) grants principals permissions to access restrictedLogEntry
fields, if any, in a given bucket. See Field-level access control for details.roles/logging.logWriter
(Logs Writer) grants principals the minimal permissions required to write logs to the Logging API. This role doesn't grant viewing permissions.roles/logging.bucketWriter
(Logs Buckets Writer) grants a sink's service account the minimal permissions required to route logs to a specific bucket. For instructions about granting permissions to a sink's service account, see Set destination permissions.roles/logging.configWriter
(Logs Configuration Writer) grants principals the permissions to create or modify logging configurations, such as sinks, buckets, views, log-based metrics, or exclusions. To use the Logs Explorer for these actions, addroles/logging.viewer
.
roles/viewer
(Project Viewer) is the same asroles/logging.viewer
. The role grants principals read-only access to all Logging features except for viewing Data Access audit logs that are in the_Default
bucket.roles/editor
(Project Editor) includes the permissions ofroles/logging.viewer
, plus permissions to write log entries, delete logs, and create log-based metrics. The role doesn't let principals create sinks or read Data Access audit logs that are in the_Default
bucket.roles/owner
(Project Owner) grants principals full access to Logging, including reading Data Access audit logs.
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 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, then 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 orlogging.privateLogEntries.list |
projects, organizations, folders, billing accounts |
entries.tail |
logging.logEntries.list orlogging.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 |
Cloud 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 log-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 log-based metrics | Add logging.logMetrics. {list , create , get , update , delete } |
Add ability to save queries | Add logging.queries. {list , create , get , update , delete } |
Add ability to share queries | Add logging.queries.share |
Add ability to use recent queries | Add logging.queries. {create , list } |
Command-line permissions
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.
Log-routing permissions
For information about setting access controls when creating and managing sinks to route logs, see Configure sinks: 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.
Log-based metrics permissions
Following is a summary of the common roles and permissions that a principal needs to access log-based metrics:
Logs Configuration Writer (
roles/logging.configWriter
) lets principals list, create, get, update, and delete log-based metrics.Logs Viewer (
roles/logging.viewer
) lets principals view existing metrics. You can also add thelogging.logMetrics.get
andlogging.logMetrics.list
permissions to a custom role.Monitoring Viewer (
roles/monitoring.viewer
) lets principals read TimeSeries data. You can also add themonitoring.timeSeries.list
permission to a custom role.Logging Admin (
roles/logging.admin
), Project Editor (roles/editor
), and Project Owner (roles/owner
) let principals create log-based metrics (logging.logMetrics.create
).
Log-based alerts permissions
Following is a summary of the common roles and permissions that a principal needs to create and manage log-based alerts:
Logging Admin (
roles/logging.admin
). Specifically, a principal needs the following permissions to read logs and to manage Logging notification rules:logging.logs.list
logging.logEntries.list
logging.notificationRules.create
logging.notificationRules.update
These permissions are included in the Logging Admin role. If you don't want to grant this role, then do the following:
- Grant the Logs Configuration Writer
(
roles/logging.configWriter
) and Logs Viewer (roles/logging.viewer
) roles. - Create a custom role and include these permissions. For more information, see Creating and managing custom roles.
Monitoring AlertPolicy Editor (
roles/monitoring.alertPolicyEditor
) and Monitoring NotificationChannel Editor (roles/monitoring.notificationChannelEditor
) include the permissions necessary to manage the alerting policies and notification channels used by log-based alerts:monitoring.alertPolicies.{create, delete, get, list, update}
monitoring.notificationChannelDescriptors.{get, list}
monitoring.notificationChannels.{create, delete, get, list, sendVerificationCode, update, verify}
The necessary permissions are also included in the Monitoring Editor (
roles/monitoring.editor
) and Monitoring Admin (roles/monitoring.admin
) roles.If you don't want to grant any of these roles, then create a custom role and include the permissions in the Monitoring AlertPolicy Editor and Monitoring NotificationChannel Editor roles.
- For more information about custom roles, see Creating and managing custom roles.
- For more information on Monitoring roles and permissions, see Access control.
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.