Configure bucket-level access

This document describes how to create and manage log views on your Cloud Logging buckets. Log views give you advanced and granular control over who has access to the logs within your log buckets.

Cloud Logging automatically creates the _AllLogs view for every bucket, which shows all logs. Cloud Logging also creates a view for the _Default bucket called _Default. The _Default view for the _Default bucket shows all logs except Data Access audit logs. The _AllLogs and _Default views are not editable.

For general information about the Logging storage model, see Routing and storage overview.

The following instructions explain how to create, view, update, and delete log views in a Google Cloud project by using the gcloud CLI.

Before you begin

Before you create or update a log view, complete the following steps:

If you haven't already done so, in the appropriate Google Cloud project, create a Logging bucket for which you want to configure a custom log view.
Ensure you have one of the suggested IAM roles for your Google Cloud project:
- roles/logging.admin
- roles/logging.configWriter
These roles include the necessary logging.views.* permissions required to create, view, update, and delete log views.
If you're using the command line, then install the Google Cloud CLI.
Determine which logs you want to include in the view. You use this information to specify the filter of the log view.

Filters

Each log view contains a filter, which restricts the log entries that are visible in the view. If the filter is empty, then the log view selects all available logs for the resource.

Filters are a logical AND, comparing any of the following values:

A data source using the source function. The source function returns log entries from a particular resource in the organizations, folders, and Google Cloud projects hierarchy.
A log ID using the log_id function. The log_id function returns log entries that match the given LOG_ID argument from the logName field.
A valid resource type using the resource.type= FIELD_NAME comparison.

For example, the following filter captures Compute Engine stdout log entries from a Google Cloud project called myproject:

source("projects/myproject") AND resource.type = "gce_instance" AND log_id("stdout")

The filter for a log view cannot contain OR operators. Log views only support AND and NOT operations.

For details about the filtering syntax, see Comparisons.

Create a log view

You can create a maximum of 30 log views per log bucket.

To create a log view that only matches Compute Engine log entries in the bucket, run the following command, after replacing the variables with your own information:

gcloud logging views create VIEW_ID --bucket=BUCKET_NAME --location=LOCATION --log-filter='resource.type="gce_instance"'

In the previous command, the VIEW_ID variable is the identifier of the log view. Use a descriptive name to easily identify your log view. Also, ensure that you set the value of the LOCATION variable to the location of the bucket specified by the BUCKET_NAME variable. For example, if the location of the bucket is us-central1, then the previous command must include the statement --location=us-central1. For more information on supported regions, see Understand data regions.

For complete information about the command to create a log view, see gcloud logging views create.

List the views for your bucket to confirm that your view was created:

gcloud logging views list --bucket=BUCKET_NAME --location=LOCATION

Grant access to a log view

To add users to a view to let them access the logs, complete the following steps.

gcloud

Get the project's IAM policy and write it to a local file in JSON format:

gcloud projects get-iam-policy PROJECT_ID --format json > output.json

Add an IAM condition that lets the user read from the bucket you created. For example:

{
  "bindings": [
    {
      "members": [
        "user:username@gmail.com"
      ],
      "role": "roles/logging.viewAccessor",
      "condition": {
          "title": "Bucket reader condition example",
          "description": "Grants logging.viewAccessor role to user username@gmail.com for the [VIEW_ID] log view.",
          "expression":
            "resource.name == \"projects/[PROJECT_ID]/locations/[LOCATION]/buckets/[BUCKET_NAME]/views/[VIEW_ID]\""
      }
    }
  ],
  "etag": "BwWd_6eERR4=",
  "version": 3
}

Update the IAM policy:

gcloud projects set-iam-policy PROJECT_ID output.json

Console

In the Google Cloud console for the project where you created the bucket, go to the IAM page.

Go to the IAM page
Click Grant access.
In the New principals field, add the user's email account.
In the Select a role drop-down menu, select Logs Views Accessor.

This role provides users with read access to all views. To limit user access to a specific view, add a condition based on the resource name.
1. Click Add IAM condition.
2. Enter a Title and Description for the condition.
3. In the Condition type drop-down menu, select Resource > Name.
4. In the Operator drop-down menu, select is.
5. In the Value field, enter the ID of the log view, including the full path to the view.
  
  For example:
```
projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_NAME/views/VIEW_ID
```
6. Click Save to add the condition.
Click Save to set the permissions.

For more information, see IAM Conditions overview.

Update a log view

To update a log view, run the following command, after replacing the variables with your own information:

gcloud logging views update VIEW_ID \
  --log-filter="resource.type=gce_instance" --bucket=NEW_BUCKET_NAME \
  --location=LOCATION --description="New description for the log view"

List the views for your bucket to confirm that your view was updated:

gcloud logging views list --bucket=NEW_BUCKET_NAME --location=LOCATION

You can't update the _Default and _AllLogs views.

Delete a log view

To delete a log view, run the following command, after replacing the variables with your own information:

gcloud logging views delete VIEW_ID \
  --bucket=BUCKET_NAME --location=LOCATION

List the views for your bucket to confirm that your view was deleted:

gcloud logging views list --bucket=BUCKET_NAME --location=LOCATION

List log views

To list all log views defined on a bucket, use the following command, after replacing the variables with your own information:

gcloud logging views list --bucket=BUCKET_NAME --location=LOCATION

The following output includes two view IDs, _AllLogs and test_view:

VIEW_ID: _AllLogs
FILTER:
CREATE_TIME:
UPDATE_TIME:

VIEW_ID: test_view
FILTER:
CREATE_TIME: 2022-07-20T20:50:55.488082225Z
UPDATE_TIME: 2022-07-20T20:50:55.488082225Z

Describe a log view

You can retrieve information about a log view by using the gcloud logging views describe command.

To describe a log view, run the following command, after replacing the variables with your own information:

gcloud logging views describe VIEW_ID --bucket=BUCKET_NAME --location=LOCATION

In the previous command, VIEW_ID is the name of the view whose details you want to display. If you don't know the view name, you can display a list of views for a bucket. For more information, see List log views.

View logs associated with a log view

To view logs in a log view, ensure you have the roles/logging.viewAccessor role for the log view.

Go to the Logs Explorer.

Go to Logs Explorer

Click Refine scope to display the Refine scope panel. From here, you can select the log bucket and log view you want to use to view your logs.

The Refine scope panel

For more information, see the Logs Explorer documentation.

What's next

Go to the Logs Explorer to verify that the view you created provides access to the correct logs.

Go to Logs Explorer