Work with retention rules - Amazon Elastic Compute Cloud
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Work with retention rules

To enable and use Recycle Bin, you must create retention rules in the Amazon Regions in which you want to protect your resources. Retention rules specify the following:

  • The resource type that you want to protect.

  • The resources that you want to retain in the Recycle Bin when they are deleted.

  • The retention period for which to retain resources in the Recycle Bin before they are permanently deleted.

With Recycle Bin, you can create two types of retention rules:

  • Tag-level retention rules — A tag-level retention rule uses resource tags to identify the resources that are to be retained in the Recycle Bin. For each retention rule, you specify one or more tag key and value pairs. Resources of the specified type that are tagged with at least one of the tag key and value pairs that are specified in the retention rule are automatically retained in the Recycle Bin upon deletion. Use this type of retention rule if you want to protect specific resources in your account based on their tags.

  • Region-level retention rules — A Region-level retention rule does not have any resource tags specified. It applies to all of the resources of the specified type in the Region in which the rule is created, even if the resources are not tagged. Use this type of retention rule if you want to protect all resources of a specific type in a specific Region.

After you create a retention rule, resources that match its criteria are automatically retained in the Recycle Bin for the specified retention period after they are deleted.

Create a retention rule

When you create a retention rule, you must specify the following required parameters:

  • The resource type that is to be protected by the retention rule.

  • The resources that are to be protected by the retention rule. You can create retention rules at the tag level and the Region level.

    • To create a tag-level retention rule, specify the resource tags that identify the resources to protect. You can specify up to 50 tags for each rule, and add the same tag key and value pair to a maximum of five retention rules.

    • To create a Region-level retention rule, do not specify any tag key and value pairs. In this case, all resources of the specified type are protected.

  • The period to retain the resources in the Recycle Bin after they are deleted. The period can be up to 1 year (365 days).

You can also specify the following optional parameters:

  • An optional name for the retention rule. The name can be up to 255 characters long.

  • An optional description for the retention rule. The description can be up to 255 characters long.

    Note

    We recommend that you do not include personally identifying, confidential, or sensitive information in the retention rule description.

  • Optional retention rule tags to help identify and organize your retention rules. You can assign up to 50 tags to each rule.

You can also optionally lock retention rules on creation. If you lock a retention rule on creation, you must also specify the unlock delay period, which can be 7 to 30 days. Retention rules remain unlocked by default unless you explicitly lock them.

Retention rules function only in the Regions in which they are created. If you intend to use Recycle Bin in other Regions, you must create additional retention rules in those Regions.

You can create a Recycle Bin retention rule using one of the following methods.

Recycle Bin console
To create a retention rule
  1. Open the Recycle Bin console at https://console.amazonaws.cn/rbin/home/

  2. In the navigation pane, choose Retention rules, and then choose Create retention rule.

  3. In the Rule details section, do the following:

    1. (Optional) For Retention rule name, enter a descriptive name for the retention rule.

    2. (Optional) For Retention rule description, enter a brief description for the retention rule.

  4. In the Rule settings section, do the following:

    1. For Resource type, select choose the type of resource for the retention rule to protect. The retention rule will retain only resources of this type in the Recycle Bin.

    2. Do one of the following:

      • To create a Region-level retention rule that matches all deleted resources of the specified type in the Region, select Apply to all resources. The retention rule will retain all deleted resources of the specified in the Recycle Bin upon deletion, even if the resources do not have any tags.

      • To create a tag-level retention rule, for Resource tags to match, enter the tag key and value pairs to use to identify resource of the specified type that are to be retained in the Recycle Bin. Only resources of the specified type that have at least one of the specified tag key and value pairs will be retained by the retention rule.

    3. For Retention period, enter the number of days for which the retention rule is to retain resources in the Recycle Bin.

  5. (Optional) To lock the retention rule, for Rule lock settings, select Lock, and then for Unlock delay period, specify the unlock delay period in days. A locked retention rule can't be modified or deleted. To modify or delete the rule, you must first unlock it and then wait for the unlock delay period to expire. For more information, see Lock retention rules

    To leave the retention rule unlocked, for Rule lock settings, keep Unlock selected. An unlocked retention rule can be modified or deleted at any time. For more information, see Unlock retention rules.

  6. (Optional) In the Tags section, do the following:

    1. To tag the rule with custom tags, choose Add tag and then enter the tag key and value pair.

  7. Choose Create retention rule.

Amazon CLI
To create a retention rule

Use the create-rule Amazon CLI command. For --retention-period, specify the number of days to retain deleted snapshots in the Recycle Bin. For --resource-type, specify EBS_SNAPSHOT for snapshots or EC2_IMAGE for AMIs. To create a tag-level retention rule, for --resource-tags, specify the tags to use to identify the snapshots that are to be retained. To create a Region-level retention rule, omit --resource-tags. To lock a retention rule, include --lock-configuration, and specify the unlock delay period in days.

$ aws rbin create-rule \ --retention-period RetentionPeriodValue=number_of_days,RetentionPeriodUnit=DAYS \ --resource-type EBS_SNAPSHOT|EC2_IMAGE \ --description "rule_description" \ --lock-configuration 'UnlockDelay={UnlockDelayUnit=DAYS,UnlockDelayValue=unlock_delay_in_days}' \ --resource-tags ResourceTagKey=tag_key,ResourceTagValue=tag_value
Example 1

The following example command creates an unlocked Region-level retention rule that retains all deleted snapshots for a period of 7 days.

$ aws rbin create-rule \ --retention-period RetentionPeriodValue=7,RetentionPeriodUnit=DAYS \ --resource-type EBS_SNAPSHOT \ --description "Match all snapshots"
Example 2

The following example command creates a tag-level rule that retains deleted snapshots that are tagged with purpose=production for a period of 7 days.

$ aws rbin create-rule \ --retention-period RetentionPeriodValue=7,RetentionPeriodUnit=DAYS \ --resource-type EBS_SNAPSHOT \ --description "Match snapshots with a specific tag" \ --resource-tags ResourceTagKey=purpose,ResourceTagValue=production
Example 3

The following example command creates a locked Region-level retention rule that retains all deleted snapshots for a period of 7 days. The retention rule is locked with an unlock delay period of 7 days.

$ aws rbin create-rule \ --retention-period RetentionPeriodValue=7,RetentionPeriodUnit=DAYS \ --resource-type EBS_SNAPSHOT \ --description "Match all snapshots" \ --lock-configuration 'UnlockDelay={UnlockDelayUnit=DAYS,UnlockDelayValue=7}'

View Recycle Bin retention rules

You can view Recycle Bin retention rules using one of the following methods.

Recycle Bin console
To view retention rules
  1. Open the Recycle Bin console at https://console.amazonaws.cn/rbin/home/

  2. In the navigation pane, choose Retention rules.

  3. The grid lists all of the retention rules for the selected Region. To view more information about a specific retention rule, select it in the grid.

Amazon CLI
To view all of your retention rules

Use the list-rules Amazon CLI command, and for --resource-type, specify EBS_SNAPSHOT for snapshots or EC2_IMAGE for AMIs.

$ aws rbin list-rules --resource-type EBS_SNAPSHOT|EC2_IMAGE
Example

The following example command provides lists all retention rules that retain snapshots.

$ aws rbin list-rules --resource-type EBS_SNAPSHOT
To view information for a specific retention rule

Use the get-rule Amazon CLI command.

$ aws rbin get-rule --identifier rule_ID
Example

The following example command provides information about retention rule pwxIkFcvge4.

$ aws rbin get-rule --identifier pwxIkFcvge4

Update retention rules

You can update an unlocked retention rule's description, resource tags, and retention period at any time after creation. You can't update a retention rule's resource type or unlock delay period, even if the retention rule is unlocked.

You can't update a locked retention rule in any way. If you need to modify a locked retention rule, you must first unlock it and wait for the unlock delay period to expire.

If you need to modify the unlock delay period for a locked retention rule, you must unlock the retention rule, and wait for the current unlock delay period to expire. When the unlock delay period is expired, you must relock the retention rule and specify the new unlock delay period.

Note

We recommend that you do not include personally identifying, confidential, or sensitive information in the retention rule description.

After you update a retention rule, the changes only apply to new resources that it retains. The changes do not affect resources that it previously sent to the Recycle Bin. For example, if you update a retention rule's retention period, only snapshots that are deleted after the update are retained for the new retention period. Snapshots that it sent to the Recycle Bin before the update are still retained for the previous (old) retention period.

You can update a retention rule using one of the following methods.

Recycle Bin console
To update a retention rule
  1. Open the Recycle Bin console at https://console.amazonaws.cn/rbin/home/

  2. In the navigation pane, choose Retention rules.

  3. In the grid, select the retention rule to update, and choose Actions, Edit retention rule.

  4. In the Rule details section, update Retention rule name and Retention rule description as needed.

  5. In the Rule settings section, update the Resource type, Resource tags to match, and Retention period as needed.

  6. In the Tags section, add or remove retention rule tags as needed.

  7. Choose Save retention rule.

Amazon CLI
To update a retention rule

Use the update-rule Amazon CLI command. For --identifier, specify the ID of the retention rule to update For --resource-types, specify EBS_SNAPSHOT for snapshots or EC2_IMAGE for AMIs.

$ aws rbin update-rule \ --identifier rule_ID \ --retention-period RetentionPeriodValue=number_of_days,RetentionPeriodUnit=DAYS \ --resource-type EBS_SNAPSHOT|EC2_IMAGE \ --description "rule_description"
Example

The following example command updates retention rule 6lsJ2Fa9nh9 to retain all snapshots for 7 days and updates its description.

$ aws rbin update-rule \ --identifier 6lsJ2Fa9nh9 \ --retention-period RetentionPeriodValue=7,RetentionPeriodUnit=DAYS \ --resource-type EBS_SNAPSHOT \ --description "Retain for three weeks"

Lock retention rules

Recycle Bin lets you lock Region-level retention rules at any time.

Note

You can't lock tag-level retention rules.

A locked retention rule can't be modified or deleted, even by users who have the required IAM permissions. Lock your retention rules to help protect them against accidental or malicious modifications and deletions.

When you lock a retention rule, you must specify an unlock delay period. This is the period of time that you must wait after unlocking the retention rule before you can modify or delete it. You cannot modify or delete the retention rule during the unlock delay period. You can modify or delete the retention rule only after the unlock delay period has expired.

You can't change the unlock delay period after the retention rule has been locked. If your account permissions have been compromised, the unlock delay period gives you additional time to detect and respond to security threats. The length of this period should be longer than the time it takes for you to identify and respond to security breaches. To set the right duration, you can review previous security incidents and the time needed to identify and remediate an account breach.

We recommend that you use Amazon EventBridge rules to notify you of retention rule lock state changes. For more information, see Monitor Recycle Bin using Amazon EventBridge.

Considerations

  • You can lock Region-level retention rules only.

  • You can lock an unlocked retention rule at any time.

  • The unlock delay period must be 7 to 30 days.

  • You can re-lock a retention rule during the unlock delay period. Relocking the retention rule resets the unlock delay period.

You can lock a Region-level retention rule using one of the following methods.

Recycle Bin console
To lock a retention rule
  1. Open the Recycle Bin console at https://console.amazonaws.cn/rbin/home/

  2. In the navigation panel, choose Retention rules.

  3. In the grid, select the unlocked retention rule to lock, and choose Actions, Edit retention rule lock.

  4. In the Edit retention rule lock screen, choose Lock, and then for Unlock delay period, specify the unlock delay period in days.

  5. Select the I acknowledge that locking the retention rule will prevent it from being modified or deleted check box, and then choose Save.

Amazon CLI
To lock an unlocked retention rule

Use the lock-rule Amazon CLI command. For --identifier, specify the ID of the retention rule to lock. For --lock-configuration, specify the unlock delay period in days.

$ aws rbin lock-rule \ --identifier rule_ID \ --lock-configuration 'UnlockDelay={UnlockDelayUnit=DAYS,UnlockDelayValue=number_of_days}'
Example

The following example command locks retention rule 6lsJ2Fa9nh9 and sets the unlock delay period to 15 days.

$ aws rbin lock-rule \ --identifier 6lsJ2Fa9nh9 \ --lock-configuration 'UnlockDelay={UnlockDelayUnit=DAYS,UnlockDelayValue=15}'

Unlock retention rules

You can't modify or delete a locked retention rule. If you need to modify a locked retention rule, you must first unlock it. After you have unlocked the retention rule, you must wait for the unlock delay period to expire before you modify or delete it. You can't modify or delete a retention rule during the unlock delay period.

An unlocked retention rule can be modified and deleted at any time by a user who has the required IAM permissions. Leaving your retention rules unlocked could expose them to accidental or malicious modifications and deletions.

Considerations

  • You can re-lock a retention rule during the unlock delay period.

  • You can re-lock a retention rule after the unlock delay period has expired.

  • You can't bypass the unlock delay period.

  • You can't change the unlock delay period after the initial lock.

We recommend that you use Amazon EventBridge rules to notify you of retention rule lock state changes. For more information, see Monitor Recycle Bin using Amazon EventBridge.

You can unlock a locked Region-level retention rule using one of the following methods.

Recycle Bin console
To unlock a retention rule
  1. Open the Recycle Bin console at https://console.amazonaws.cn/rbin/home/

  2. In the navigation panel, choose Retention rules.

  3. In the grid, select the locked retention rule to unlock, and choose Actions, Edit retention rule lock.

  4. On the Edit retention rule lock screen, choose Unlock, and then choose Save.

Amazon CLI
To unlock a locked retention rule

Use the unlock-rule Amazon CLI command. For --identifier, specify the ID of the retention rule to unlock.

$ aws rbin unlock-rule \ --identifier rule_ID
Example

The following example command unlocks retention rule 6lsJ2Fa9nh9

$ aws rbin unlock-rule \ --identifier 6lsJ2Fa9nh9

Tag retention rules

You can assign custom tags to your retention rules to categorize them in different ways, for example, by purpose, owner, or environment. This helps you to efficiently find a specific retention rule based on the custom tags that you assigned.

You can assign a tag to a retention rule using one of the following methods.

Recycle Bin console
To tag a retention rule
  1. Open the Recycle Bin console at https://console.amazonaws.cn/rbin/home/

  2. In the navigation pane, choose Retention rules.

  3. Select the retention rule to tag, choose the Tags tab, and then choose Manage tags.

  4. Choose Add tag. For Key, enter the tag key. For Value, enter the tag value.

  5. Chose Save.

Amazon CLI
To tag a retention rule

Use the tag-resource Amazon CLI command. For --resource-arn, specify the Amazon Resource Name (ARN) of the retention rule to tag, and for --tags, specify the tag key and value pair.

$ aws rbin tag-resource \ --resource-arn retention_rule_arn \ --tags key=tag_key,value=tag_value
Example

The following example command tags retention rule arn:aws:rbin:us-east-1:123456789012:rule/nOoSBBtItF3 with tag purpose=production.

$ aws rbin tag-resource \ --resource-arn arn:aws:rbin:us-east-1:123456789012:rule/nOoSBBtItF3 \ --tags key=purpose,value=production

View retention rule tags

You can view the tags assigned to a retention rule using one of the following methods.

Recycle Bin console
To view tags for a retention rule
  1. Open the Recycle Bin console at https://console.amazonaws.cn/rbin/home/

  2. In the navigation pane, choose Retention rules.

  3. Select the retention rule for which to view the tags, and choose the Tags tab.

Amazon CLI
To view the tags assigned to a retention rule

Use the list-tags-for-resource Amazon CLI command. For --resource-arn, specify the ARN of the retention rule.

$ aws rbin list-tags-for-resource \ --resource-arn retention_rule_arn
Example

The following example command lists the tags for retention rule arn:aws:rbin:us-east-1:123456789012:rule/nOoSBBtItF3.

$ aws rbin list-tags-for-resource \ --resource-arn arn:aws:rbin:us-east-1:123456789012:rule/nOoSBBtItF3

Remove tags from retention rules

You can remove tags from a retention rule using one of the following methods.

Recycle Bin console
To remove a tag from a retention rule
  1. Open the Recycle Bin console at https://console.amazonaws.cn/rbin/home/

  2. In the navigation pane, choose Retention rules.

  3. Select the retention rule from which to remove the tag, choose the Tags tab, and then choose Manage tags.

  4. Choose Remove next to the tag to remove.

  5. Chose Save.

Amazon CLI
To remove a tag from a retention rule

Use the untag-resource Amazon CLI command. For --resource-arn, specify the ARN of the retention rule. For --tagkeys, specify the tags keys of the tags to remove.

$ aws rbin untag-resource \ --resource-arn retention_rule_arn \ --tagkeys tag_key
Example

The following example command removes tags that have a tag key of purpose from retention rule arn:aws:rbin:us-east-1:123456789012:rule/nOoSBBtItF3.

$ aws rbin untag-resource \ --resource-arn arn:aws:rbin:us-east-1:123456789012:rule/nOoSBBtItF3 \ --tagkeys purpose

Delete Recycle Bin retention rules

You can delete a retention rule at any time. When you delete a retention rule, it no longer retains new resources in the Recycle Bin after they have been deleted. Resources that were sent to the Recycle Bin before the retention rule was deleted continue to be retained in the Recycle Bin according to the retention period defined in the retention rule. When the period expires, the resource is permanently deleted from the Recycle Bin.

You can delete a retention rule using one of the following methods.

Recycle Bin console
To delete a retention rule
  1. Open the Recycle Bin console at https://console.amazonaws.cn/rbin/home/

  2. In the navigation pane, choose Retention rules.

  3. In the grid, select the retention rule to delete, and choose Actions, Delete retention rule.

  4. When prompted, enter the confirmation message and choose Delete retention rule.

Amazon CLI
To delete a retention rule

Use the delete-rule Amazon CLI command. For --identifier, specify the ID of the retention rule to delete.

$ aws rbin delete-rule --identifier rule_ID
Example

The following example command deletes retention rule 6lsJ2Fa9nh9.

$ aws rbin delete-rule --identifier 6lsJ2Fa9nh9