Manage log buckets by using Tags

This document describes how to use Tags to manage your Cloud Logging log buckets. Tags, which are created at the organization- or project-level, let you annotate your resources. You can also conditionally grant Identity and Access Management (IAM) roles or conditionally deny IAM permissions based on whether a resource has a specific tag. For information about tags, see Tags overview.

For example, if you use BigQuery to analyze your Cloud Billing data, then you might attach the project:production tag to log buckets that store log data from production resources, and you might attach the project:development tag to log buckets that store log data from development resources. Then, you can query Cloud Billing data with tags and see a breakdown of your costs between development and production.

Tags can be explicitly attached to log buckets, or inherited from their parent organization, folders, and projects.

Before you begin

To get started with managing your log buckets by using tags, do the following:

  1. Ensure that you've created a tag and configured its values. You use Resource Manager to manage tag definitions. For information about how to create and manage tags, see Creating and managing tags.

  2. To get the permissions that you need to manage your log buckets by using tags, ask your administrator to grant you the following IAM roles on project or organization:

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

    These predefined roles contain the permissions required to manage your log buckets by using tags. To see the exact permissions that are required, expand the Required permissions section:

    Required permissions

    The following permissions are required to manage your log buckets by using tags:

    • Add or remove tags to log buckets:
      • resourcemanager.tagValues.{get,list}
      • resourcemanager.tagKeys.{get,list}
      • resourcemanager.projects.get
      • logging.buckets.createTagbinding
      • logging.buckets.deleteTagBinding
    • View tags that are attached to log buckets:
      • resourcemanager.tagValues.{get,list}
      • resourcemanager.tagKeys.{get,list}
      • logging.buckets.listTagBindings
      • logging.buckets.listEffectiveTags

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

  3. To get the permission that you need to manage log buckets, ask your administrator to grant you the Logs Configuration Writer (roles/logging.configWriter) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.

    This predefined role contains the logging.buckets.list permission, which is required to manage log buckets.

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

Attach tags to a log bucket

To attach a tag to a log bucket, do the following:

Google Cloud console

  1. In the Google Cloud console, go to the Logs Storage page:

    Go to Logs Storage

    If you use the search bar to find this page, then select the result whose subheading is Logging.

  2. Locate the log bucket to attach a tag to.

  3. On the log bucket, click More, and then click Edit tags.

  4. In the dialog, in the Direct tags section, locate the tag by selecting the resource in which the tag was created. For example, to use a tag that was created at the project-level, choose Select current project as the scope.

    You can also manually search for the project, organization, or tag ID by selecting the Manual Entry option.

  5. Select the appropriate key-value pair, then click Save.

  6. A dialog confirming your changes appears. Click Confirm to finalize your changes.

gcloud

To attach a tag to a log bucket, create a tag binding by running the gcloud resource-manager tags bindings create command:

gcloud resource-manager tags bindings create \
--tag-value=TAG_VALUE_ID \
--parent=BUCKET_NAME \
--location=LOCATION

In the previous command, make the following replacements:

  • TAG_VALUE_ID: The permanent ID or the namespaced name of the tag value. For example, tagValues/4567890123. For more information about tag identifiers, see Tag definitions and identifiers.

  • BUCKET_NAME: The name of the log bucket. For example, logging.googleapis.com/projects/BUCKET_PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID.

  • LOCATION: The location of the log bucket.

API

To attach a tag to a log bucket, use the tagBindings.create method.

View tags attached to a log bucket

To view the tags attached to a log bucket, do the following:

Google Cloud console

  1. In the Google Cloud console, go to the Logs Storage page:

    Go to Logs Storage

    If you use the search bar to find this page, then select the result whose subheading is Logging.

  2. Locate the log bucket whose tags you want to view.

    In the Tags column, a tag associated with the log bucket is listed. To view all tags associated with the log bucket, click the More button to expand the list of tags.

gcloud

Run the gcloud resource-manager tags bindings list command:

gcloud resource-manager tags bindings list \
--parent=BUCKET_NAME \
--location=LOCATION

In the previous command, make the following replacements:

  • TAG_VALUE_ID: The permanent ID or the namespaced name of the tag value. For example, tagValues/4567890123. For more information about tag identifiers, see Tag definitions and identifiers.

  • BUCKET_NAME: The name of the log bucket. For example, logging.googleapis.com/projects/BUCKET_PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID.

  • LOCATION: The location of the log bucket.

Optional: To view tags inherited by the log bucket, add the --effective flag, Adding this flag returns a response similar to the following:

namespacedTagKey: 961309089256/environment
namespacedTagValue: 961309089256/environment/production
tagKey: tagKeys/417628178507
tagValue: tagValues/247197504380
inherited: true

If all tags are explicitly attached to the log bucket and no tags are inherited, then the inherited field is false and is omitted.

API

To get a list of tag bindings for a bucket, use the tagBindings.list method.

Remove tags on a log bucket

To remove the tags attached to a log bucket, you must delete the tag binding attached to the log bucket. To delete a tag, you must remove the tags from all attached resources.

Google Cloud console

  1. In the Google Cloud console, go to the Logs Storage page:

    Go to Logs Storage

    If you use the search bar to find this page, then select the result whose subheading is Logging.

  2. Locate the log bucket whose tag you want to remove.

  3. On the log bucket, click More, and then click Edit tags.

  4. In the dialog, hold the pointer over the tag to remove, and click Delete item. Click Save to save your changes.

  5. A dialog confirming your changes appears. Click Confirm to finalize your changes.

gcloud

Run the gcloud resource-manager tags bindings delete command:

gcloud resource-manager tags bindings delete \
--tag-value=TAG_VALUE_ID \
--parent=BUCKET_NAME \
--location=LOCATION

In the previous command, make the following replacements:

  • TAG_VALUE_ID: The permanent ID or the namespaced name of the tag value. For example, tagValues/4567890123. For more information about tag identifiers, see Tag definitions and identifiers.

  • BUCKET_NAME: The name of the log bucket. For example, logging.googleapis.com/projects/BUCKET_PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID.

  • LOCATION: The location of the log bucket.

API

To remove a tag on a log bucket, use the tagBindings.delete method.

Limitations

  • You can't use IAM role grants to control which log buckets a principal sees when they list the log buckets in a Google Cloud project. A principal will see either a complete list or an empty list. However, you can use IAM role grants with IAM conditions to restrict the actions that a principal can take on a log bucket. For example, you can restrict whether a principal can delete a specific log bucket.

  • If you use Cloud Billing data exports with BigQuery, then tags might take up to an hour to be used in the export. If a tag has been added or removed within an hour, or if the log bucket has existed for less than an hour, then it might not appear in the export.

Custom roles and role grants with IAM conditions

If you plan to use custom IAM roles and if you plan to attach IAM conditions to the role grants, then you might need to create multiple custom roles. Some IAM permissions are invalidated when an IAM condition is attached to a role grant.

For Cloud Logging, the following IAM permissions are invalidated when a role grant contains an IAM condition:

  • logging.buckets.list
  • logging.buckets.create

Therefore, you might need to create one role with the list and create permissions and another role that contains other bucket-specific permissions. For example, you might create a role that contains the logging.buckets.delete and logging.buckets.update permissions.

When you grant the role that contains the list and create permissions, don't attach an IAM condition to the role grant. When you grant the role that contains the delete and update permissions, then you can add an IAM condition that restricts the grant to resources with a specific tag.

What's next