Use tags to set a default soft delete retention duration for new buckets

This page describes how to set a default soft delete retention duration for your organization using tags.

Overview

Tags let you customize a default soft delete retention duration so that each time you create a new bucket, its soft delete retention duration is automatically set to a length of time of your choice. Tags let you attach a key-value pair to your resource that represents the amount of days you want Cloud Storage to retain soft-deleted data in your buckets. While the system's default soft delete retention duration is seven days, tags give you greater control over object retention by letting you increase the number of days your data is retained or disabling soft delete on your resource by default.

Considerations

For a tag to take effect, you must create the tag as a child of the organization you want to set a default retention duration for, after which it can be attached to a project, Resource Manager folder, or organization.
When you use tags to customize a default soft delete retention duration on a resource, existing buckets in the resource don't automatically inherit the new soft delete retention duration. To change the soft delete retention duration on an existing bucket, you need to update the bucket's soft delete policy, see Edit a bucket's soft delete policy.
Settings that are implemented using tags are editable, meaning you can edit the soft delete retention duration that the tag sets during or after bucket creation.
If you set a storage.softDeletePolicySeconds organization policy constraint which restricts the soft delete retention duration on newly created buckets to only a set of values allowed by your organization and also want to use tags to set a default soft delete retention duration, you can only set the default retention duration to a value allowed by your organization policy constraint. All other values result in an error.
Tags can take several hours to take effect.
If you delete a tag binding that was previously set on a child resource of your organization, the child resource inherits the organization's default soft delete retention duration. If you delete the organization's tag binding, your resource inherits the soft delete system default retention duration of seven days. To learn more about how tag values are inherited, see Tag inheritance.

Required roles

The following permissions are required to perform the actions outlined in this page.

Administer tags

To create, update, and delete tag definitions, you need the Tag Administrator role (roles/resourcemanager.tagAdmin).
To administer tags at the organization level, you need the Organization Viewer role (roles/resourcemanager.organizationViewer) on the organization resource.

Required permissions

resourcemanager.tagKeys.create
resourcemanager.tagKeys.update
resourcemanager.tagKeys.delete
resourcemanager.tagKeys.list
resourcemanager.tagKeys.get
resourcemanager.tagKeys.getIamPolicy
resourcemanager.tagKeys.setIamPolicy
resourcemanager.tagValues.create
resourcemanager.tagValues.update
resourcemanager.tagValues.delete
resourcemanager.tagValues.list
resourcemanager.tagValues.get
resourcemanager.tagValues.getIamPolicy
resourcemanager.tagValues.setIamPolicy

Manage tags

To add and remove tags that are attached to resources, you need the Tag User role (roles/resourcemanager.tagUser), or another role with equivalent permissions, on both the tag value and the resources that you are attaching the tag value to.

Required permissions

Permissions required for the resource you're attaching the tag value

Resource-specific createTagBinding permission, such as compute.instances.createTagBinding for Compute Engine instances.
Resource-specific deleteTagBinding permission, such as compute.instances.deleteTagBinding for Compute Engine instances.

Permissions required for the tag value:

resourcemanager.tagValueBindings.create
resourcemanager.tagValueBindings.delete

Permissions that let you view projects and tag definitions:

resourcemanager.tagValues.get
resourcemanager.tagValues.list
resourcemanager.tagKeys.get
resourcemanager.tagKeys.list
resourcemanager.projects.get

Create a default soft delete retention duration tag and tag values

To create the default soft delete retention duration tag and tag values, complete the following instructions:

Console

In the Google Cloud console, go to the Tags page.
Go to Tags
Select the parent organization you want to create a tag key for.
Click Create.
In the Tag key field, enter storage.defaultSoftDeletePolicy.

Note: Only the storage.defaultSoftDeletePolicy tag name updates the default soft delete retention duration.
In the Tag key description field, enter a description of your tag key.
Click Add value.
In the Tag value field, enter the length of time you want to set as the default soft delete retention duration. Format the retention duration as a number value between 7 to 90 days, such as 30d, or, to disable soft delete on your resource by default, enter 0d.
In the Tag value description field, enter a description of your tag value.
Click Create tag key.

The newly created tag appears in the Tag keys list.

Command line

Create a tag using the gcloud resource-manager tags key create command. Note that only the storage.defaultSoftDeletePolicy tag name updates the default soft delete policy.
```
gcloud resource-manager tags keys create storage.defaultSoftDeletePolicy \
--parent=organizations/ORGANIZATION_ID \
--description="Configures the default softDeletePolicy for new Storage buckets."
```
Replace the following:
- ORGANIZATION_ID: the numeric ID of the organization you want to set a default soft delete retention duration for. For example, 12345678901.
Add a tag value using the gcloud resource-manager tags values create command and replace the following:
```
gcloud resource-manager tags values create RETENTION_DURATION \
 --parent=ORGANIZATION_ID/storage.defaultSoftDeletePolicy \
 --description="Sets the default soft delete retention duration for new Storage buckets to $duration."
done
```
- RETENTION_DURATION: the length of time you want to set as the new default soft delete retention duration. Format the retention duration as a number value between 7 to 90 days, such as 30d, or, to disable soft delete on your resource by default, enter 0d.
- ORGANIZATION_ID: the numeric ID of the organization you want to set the default soft delete retention duration for. For example, 12345678901.

Attach a default soft delete retention duration tag to a resource

After you've created a default soft delete retention duration tag and set its tag values, you must attach the tag to a resource using a tag binding resource in order for the new default soft delete retention duration to take effect. To attach a tag to a resource, complete the following instructions:

Console

In the Google Cloud console, open the Manage resources page.
Open Manage resources
Click the organization, folder, or project you want to attach a tag to.
Click Tags.
In the Tags panel, click Select scope.
Select the parent organization, then click Open.
In the Tags panel, select Add tag.
In the Key field, select the default soft delete retention duration tag. You can filter the list by typing keywords.
In the Value field, select the length of time you want to set as the default soft delete retention duration from the list. You can filter the list by typing keywords.
Click Save.
In the Confirm dialog, click Confirm to attach the tag.

A notification appears confirming that your tags are updated. The new tags appear under the Tags column on the Manage resources page.

Command line

Attach the default soft delete retention duration tag to a resource using the gcloud resource-manager tags bindings create.

 gcloud resource-manager tags bindings create \
  --tag-value=ORGANIZATION_ID/storage.defaultSoftDeletePolicy/RETENTION_DURATION \
  --parent=RESOURCE_ID

Replace the following:

ORGANIZATION_ID: the numeric ID of the organization under which the tag was created. For example, 12345678901.
RETENTION_DURATION: the length of time you want to set the new default soft delete retention duration to. Format the retention duration as a number value between 7 to 90 days, such as 30d, or, to disable soft delete on your resource by default, enter 0d.
RESOURCE_ID: the full name of the folder, project, or organization you want to create the tag binding for. For example, to attach a tag to projects/7890123456, enter //cloudresourcemanager.googleapis.com/projects/7890123456.

Remove a default soft delete retention duration tag from a resource

You can remove a default soft delete retention duration tag from a resource by deleting the tag binding resource. To delete a tag binding resource, complete the following instructions:

Console

In the Google Cloud console, open the Manage resources page.
Open Manage resources
Click the organization, folder, or project from which you want to detach a tag.
Click Tags.
In the Tags panel, next to the tag you want to detach, click Delete item.
Click Save.
In the Confirm dialog, click Confirm to detach the tag.

A notification appears confirming that your tags are updated. The updated list of tags appears under the Tags column on the Manage resources page.

Command line

Delete a tag binding using the gcloud resource-manager tag bindings delete command:

 gcloud resource-manager tags bindings delete \
  --tag-value=ORGANIZATION_ID/storage.defaultSoftDeletePolicy/RETENTION_DURATION \
  --parent=RESOURCE_ID

Replace the following:

ORGANIZATION_ID: the numeric ID you used to set your default soft delete retention duration. For example, 12345678901.
RETENTION_DURATION: the length of time you entered as the default soft delete retention duration for your resource. For example, if you set a default soft delete retention duration of 10 days, enter 10d.
RESOURCE_ID: the full name of the folder, project, or organization you want to delete the tag binding for.

What's next

Learn how to use soft-deleted objects.
Learn more about Resource Manager tag creation and management.