Access control with IAM

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

(roles/logging.admin)

Provides all permissions necessary to use all features of Cloud Logging.

Lowest-level resources where you can grant this role:

  • Project

logging.buckets.copyLogEntries

logging.buckets.create

logging.buckets.createTagBinding

logging.buckets.delete

logging.buckets.deleteTagBinding

logging.buckets.get

logging.buckets.list

logging.buckets.listEffectiveTags

logging.buckets.listTagBindings

logging.buckets.undelete

logging.buckets.update

logging.exclusions.*

  • logging.exclusions.create
  • logging.exclusions.delete
  • logging.exclusions.get
  • logging.exclusions.list
  • logging.exclusions.update

logging.fields.access

logging.links.*

  • logging.links.create
  • logging.links.delete
  • logging.links.get
  • logging.links.list

logging.locations.*

  • logging.locations.get
  • logging.locations.list

logging.logEntries.*

  • logging.logEntries.create
  • logging.logEntries.download
  • logging.logEntries.list
  • logging.logEntries.route

logging.logMetrics.*

  • logging.logMetrics.create
  • logging.logMetrics.delete
  • logging.logMetrics.get
  • logging.logMetrics.list
  • logging.logMetrics.update

logging.logServiceIndexes.list

logging.logServices.list

logging.logs.*

  • logging.logs.delete
  • logging.logs.list

logging.notificationRules.*

  • logging.notificationRules.create
  • logging.notificationRules.delete
  • logging.notificationRules.get
  • logging.notificationRules.list
  • logging.notificationRules.update

logging.operations.*

  • logging.operations.cancel
  • logging.operations.get
  • logging.operations.list

logging.privateLogEntries.list

logging.queries.*

  • logging.queries.deleteShared
  • logging.queries.getShared
  • logging.queries.listShared
  • logging.queries.share
  • logging.queries.updateShared
  • logging.queries.usePrivate

logging.settings.*

  • logging.settings.get
  • logging.settings.update

logging.sinks.*

  • logging.sinks.create
  • logging.sinks.delete
  • logging.sinks.get
  • logging.sinks.list
  • logging.sinks.update

logging.sqlAlerts.*

  • logging.sqlAlerts.create
  • logging.sqlAlerts.update

logging.usage.get

logging.views.*

  • logging.views.access
  • logging.views.create
  • logging.views.delete
  • logging.views.get
  • logging.views.getIamPolicy
  • logging.views.list
  • logging.views.listLogs
  • logging.views.listResourceKeys
  • logging.views.listResourceValues
  • logging.views.setIamPolicy
  • logging.views.update

observability.scopes.get

resourcemanager.projects.get

resourcemanager.projects.list

(roles/logging.bucketWriter)

Ability to write logs to a log bucket.

Lowest-level resources where you can grant this role:

  • Project

logging.buckets.write

(roles/logging.configWriter)

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:

  • Project

logging.buckets.create

logging.buckets.createTagBinding

logging.buckets.delete

logging.buckets.deleteTagBinding

logging.buckets.get

logging.buckets.list

logging.buckets.listEffectiveTags

logging.buckets.listTagBindings

logging.buckets.undelete

logging.buckets.update

logging.exclusions.*

  • logging.exclusions.create
  • logging.exclusions.delete
  • logging.exclusions.get
  • logging.exclusions.list
  • logging.exclusions.update

logging.links.*

  • logging.links.create
  • logging.links.delete
  • logging.links.get
  • logging.links.list

logging.locations.*

  • logging.locations.get
  • logging.locations.list

logging.logMetrics.*

  • logging.logMetrics.create
  • logging.logMetrics.delete
  • logging.logMetrics.get
  • logging.logMetrics.list
  • logging.logMetrics.update

logging.logServiceIndexes.list

logging.logServices.list

logging.logs.list

logging.notificationRules.*

  • logging.notificationRules.create
  • logging.notificationRules.delete
  • logging.notificationRules.get
  • logging.notificationRules.list
  • logging.notificationRules.update

logging.operations.*

  • logging.operations.cancel
  • logging.operations.get
  • logging.operations.list

logging.settings.*

  • logging.settings.get
  • logging.settings.update

logging.sinks.*

  • logging.sinks.create
  • logging.sinks.delete
  • logging.sinks.get
  • logging.sinks.list
  • logging.sinks.update

logging.sqlAlerts.*

  • logging.sqlAlerts.create
  • logging.sqlAlerts.update

logging.views.create

logging.views.delete

logging.views.get

logging.views.getIamPolicy

logging.views.list

logging.views.update

observability.scopes.get

resourcemanager.projects.get

resourcemanager.projects.list

(roles/logging.fieldAccessor)

Ability to read restricted fields in a log bucket.

Lowest-level resources where you can grant this role:

  • Project

logging.fields.access

(roles/logging.linkViewer)

Ability to see links for a bucket.

logging.links.get

logging.links.list

(roles/logging.logWriter)

Provides the permissions to write log entries.

Lowest-level resources where you can grant this role:

  • Project

logging.logEntries.create

logging.logEntries.route

(roles/logging.privateLogViewer)

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:

  • Project

logging.buckets.get

logging.buckets.list

logging.exclusions.get

logging.exclusions.list

logging.links.get

logging.links.list

logging.locations.*

  • logging.locations.get
  • logging.locations.list

logging.logEntries.list

logging.logMetrics.get

logging.logMetrics.list

logging.logServiceIndexes.list

logging.logServices.list

logging.logs.list

logging.privateLogEntries.list

logging.queries.getShared

logging.queries.listShared

logging.queries.usePrivate

logging.sinks.get

logging.sinks.list

logging.usage.get

logging.views.access

logging.views.get

logging.views.list

observability.scopes.get

resourcemanager.projects.get

(roles/logging.sqlAlertWriter)

Ability to write SQL Alerts.

logging.sqlAlerts.*

  • logging.sqlAlerts.create
  • logging.sqlAlerts.update

(roles/logging.viewAccessor)

Ability to read logs in a view.

Lowest-level resources where you can grant this role:

  • Project

logging.logEntries.download

logging.views.access

logging.views.listLogs

logging.views.listResourceKeys

logging.views.listResourceValues

(roles/logging.viewer)

Provides access to view logs.

Lowest-level resources where you can grant this role:

  • Project

logging.buckets.get

logging.buckets.list

logging.exclusions.get

logging.exclusions.list

logging.links.get

logging.links.list

logging.locations.*

  • logging.locations.get
  • logging.locations.list

logging.logEntries.list

logging.logMetrics.get

logging.logMetrics.list

logging.logServiceIndexes.list

logging.logServices.list

logging.logs.list

logging.operations.get

logging.operations.list

logging.queries.getShared

logging.queries.listShared

logging.queries.usePrivate

logging.sinks.get

logging.sinks.list

logging.usage.get

logging.views.get

logging.views.list

observability.scopes.get

resourcemanager.projects.get

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][log-overview-lbm] or [log-based alerting policies][log-overview-lba]. 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.
  • 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 more information about custom roles, see Understanding IAM custom roles.

Cloud Logging permissions

The following table is a partial list of the permissions needed for specific features of Cloud Logging. This table can help you identify the permissions that you need to use pages like 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 logs logging.privateLogEntries.list
View log-based metrics logging.logMetrics.[list, get]
View sinks logging.sinks.[list, get]
View logs usage logging.usage.get
Exclude logs logging.exclusions.[list, create, get, update, delete]

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.

Create and use sinks logging.sinks.[list, create, get, update, delete]

When creating a sink, you must also grant the service account an IAM role that lets it write log entries to the destination. For more information, see Set destination permissions.

After your log entries have been routed to a supported destination, access to the log entries is controlled entirely by IAM permissions and roles on the destination.

Create log-based alerts See Roles required to create and use log-based alerting policies.
Create log-based metrics logging.logMetrics.[list, create, get, update, delete]

For information about other IAM roles that you need to create and use log-based metrics, see Roles required to create and use log-based metrics.

Save and use private queries logging.queries.usePrivate
logging.queries.[listShared,getShared]
Save and use shared queries logging.queries.[share, getShared, updateShared, deleteShared, listShared]
Use recent queries logging.queries.[create, list]

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.

Roles required to create and use 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 the logging.logMetrics.get and logging.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 the monitoring.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 the logging.logMetrics.create permission to create log-based metrics.

Roles required to create and use 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 create log-based alerting policies in Monitoring and to create the associated Logging notification rules, ask your administrator to grant you the following IAM roles on your project:

    For more information about granting roles, see Manage access to projects, folders, and organizations.

    These predefined roles contain the permissions required to create log-based alerting policies in Monitoring and to create the associated Logging notification rules. To see the exact permissions that are required, expand the Required permissions section:

    Required permissions

    The following permissions are required to create log-based alerting policies in Monitoring and to create the associated Logging notification rules:

    • monitoring.alertPolicies.create
    • logging.notificationRules.create

    You might also be able to get these permissions with custom roles or other predefined roles.

If you create your alerting policy in the Google Cloud CLI, then the following role or permission is also required:

  • To get the permission that you need to create an alerting policy by using the Google Cloud CLI, ask your administrator to grant you the Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.

    This predefined role contains the serviceusage.services.use permission, which is required to create an alerting policy by using the Google Cloud CLI.

    You might also be able to get this permission with custom roles or other predefined roles.

If your Google Cloud project already has notification channels, then you can configure your alerting policy to use an existing channel without any additional roles or permissions. However, if you need to create a notification channel for your log-based alerting policy, then the following role or permission is required:

  • To get the permission that you need to create a notification channel for a log-based alerting policy, ask your administrator to grant you the Monitoring NotificationChannel Editor (roles/monitoring.notificationChannelEditor) IAM role on your project.

    This predefined role contains the monitoring.notificationChannels.create permission, which is required to create a notification channel for a log-based alerting policy.

Permissions for SQL-based alerting policies

SQL-based alerting policies evaluate the results of a SQL query run against data from groups of log entries. For information about the roles required to create and manage SQL-based alerting policies, see the Before you begin section in Monitor your SQL query results with an alerting policy.

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.