Access control guide

This page describes how Stackdriver Logging uses Cloud Identity and Access Management to control access to logging data in Google Cloud resources.

Overview

Cloud IAM permissions and roles determine how you can use the Logging API, the Logs Viewer, and the gcloud command-line tool.

Logs reside in Google Cloud projects, organizations, folders, and billing accounts. Each of these Google Cloud resources can have its own set of members with their own sets of Stackdriver Logging roles and permissions.

To use Logging with the logging data in a Google Cloud project, you must be a member and have an Cloud IAM role that grants you permission to use Logging. The following Cloud IAM roles apply to Logging:

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.
roles/logging.logWriter (Logs Writer) can be granted to service accounts to give applications just enough permissions to write logs. This role does not grant viewing permissions.
roles/logging.configWriter (Logs Configuration Writer) gives you the permissions to create logs-based metrics and exclusions, and to export sinks. To use the Logs Viewer (console) for these actions, add roles/logging.viewer.
roles/logging.admin (Logging Admin) grants you all permissions related to Logging.
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.
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 does not let you create export 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.

For more details about Logging roles and permissions, see Permissions and roles on this page.

Permissions and roles

The following table lists the Cloud IAM roles that grant access to Stackdriver Logging. Each role has a specific set of logging permissions. Roles can be assigned to members of the listed resource types.

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

Role name	Role title	Logging permissions	Resource type
`roles/` `logging.viewer`	Logs Viewer	`logging.logEntries.list` `logging.logMetrics.`{`list`, `get`} `logging.logs.list` `logging.logServiceIndexes.list` `logging.logServices.list` `logging.sinks.`{`list`, `get`} `logging.usage.get` `resourcemanager.projects.get`	project, organization, folder, billing account
`roles/` `logging.privateLogViewer`	Private Logs Viewer	`roles/logging.viewer` permissions, plus: `logging.privateLogEntries.list`	project, organization, folder, billing account
`roles/` `logging.logWriter`	Logs Writer	`logging.logEntries.create`	project, organization, folder, billing account
`roles/` `logging.configWriter`	Logs Configuration Writer	`logging.buckets.`{`list`, `create`, `get`, `update`, `delete`} `logging.exclusions.`{`list`, `create`, `get`, `update`, `delete`} `logging.logMetrics.`{`list`, `create`, `get`, `update`, `delete`} `logging.logs.list` `logging.logServiceIndexes.list` `logging.logServices.list` `logging.sinks.{list`, `create`, `get`, `update`, `delete`} `resourcemanager.projects.`{`get`, `list`}	project, organization, folder, billing account
`roles/` `logging.admin`	Logging Admin	`logging.exclusions.`{`list`, `create`, `get`, `update`, `delete`} `logging.logEntries.`{`create`, `list`} `logging.logMetrics.`{`list`, `create`, `get`, `update`, `delete`} `logging.logs.`{`delete`,`list`} `logging.logServiceIndexes.list` `logging.logServices.list` `logging.privateLogEntries.list` `logging.sinks.{list`, `create`, `get`, `update`, `delete`} `resourcemanager.projects.get` `logging.usage.get`	project, organization, folder, billing account
`roles/viewer`	Viewer	`logging.logEntries.list` `logging.logMetrics.`{`list`, `get`} `logging.logs.list` `logging.logServiceIndexes.list` `logging.logServices.list` `logging.sinks.`{`list`, `get`} `resourcemanager.projects.get`	project
`roles/editor`	Editor	`roles/viewer` Logging permissions, plus: `logging.logEntries.create` `logging.logMetrics.`{`create`, `update`, `delete`} `logging.logs.delete`	project
`roles/owner`	Owner	`roles/editor` Logging permissions, plus: `logging.privateLogEntries.list` `logging.sinks.`{`create`, `update`, `delete`}`	project

Custom roles

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

For a role granting permissions for the Logging API, choose from the permissions in API permissions.
For a role granting permissions to use the Logs Viewer, choose from permission groups in Console permissions.
For a role granting permissions to use gcloud logging, go to the overview of the gcloud tool.

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

API permissions

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

Logging method	Required permission	Resource type
`billingAccounts.logs.*`	`logging.logs.` (See `projects.logs.`)	billing accounts
`billingAccounts.sinks.*`	`logging.sinks.` (See `projects.sinks.`.)	billing accounts
`entries.list`	`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
`monitoredResourceDescriptors.list`	(none)	(none)
`organizations.logs.*`	`logging.logs.` (See `projects.logs.`)	organizations
`organizations.sinks.*`	`logging.sinks.` (See `projects.sinks.`)	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.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 Viewer.

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 Add `logging.privateLogEntries.list`
Add ability to view logs-based metrics	Add `logging.logMetrics.`{`list`, `get`}
Add ability to view exports	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 export logs	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 Cloud Identity and Access Management permissions.

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

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

Access to exported logs

To create a sink, in order to export logs, you must have the permissions of roles/logging.configWriter or roles/logging.admin or roles/owner.

Once a sink begins exporting logs, it has full access to all incoming log entries. Sinks can export private log entries, including Access Transparency logs and Data Access audit logs.

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

Logging access scopes

Access scopes are the legacy method of specifying permissions for 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	`role/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.

Best practices

Now that Cloud IAM roles are available, a reasonable practice is to give all your VM instances the "Full access to all enabled Google Cloud APIs" scope:

https://www.googleapis.com/auth/cloud-platform

You can grant specific Cloud IAM roles in your VM instance's service account to restrict access to specific APIs. For details, see Service account permissions.