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.
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
-
Open the Recycle Bin console at https://console.amazonaws.cn/rbin/home/
-
In the navigation pane, choose Retention rules, and then choose
Create retention rule.
-
In the Rule details section, do the following:
-
(Optional) For Retention rule name, enter
a descriptive name for the retention rule.
-
(Optional) For Retention rule description,
enter a brief description for the retention rule.
-
In the Rule settings section, do the following:
-
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.
-
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.
-
For Retention period, enter the number of days for which the retention
rule is to retain resources in the Recycle Bin.
-
(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.
-
(Optional) In the Tags section, do the following:
-
To tag the rule with custom tags, choose Add tag and then
enter the tag key and value pair.
-
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
-
Open the Recycle Bin console at https://console.amazonaws.cn/rbin/home/
-
In the navigation pane, choose Retention rules.
-
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.
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
-
Open the Recycle Bin console at https://console.amazonaws.cn/rbin/home/
-
In the navigation pane, choose Retention rules.
-
In the grid, select the retention rule to update, and choose
Actions, Edit retention
rule.
-
In the Rule details section, update Retention rule name
and Retention rule description as needed.
-
In the Rule settings section, update the Resource type,
Resource tags to match, and Retention period as needed.
-
In the Tags section, add or remove retention rule tags as needed.
-
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.
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
-
Open the Recycle Bin console at
https://console.amazonaws.cn/rbin/home/
-
In the navigation panel, choose Retention
rules.
-
In the grid, select the unlocked retention rule to lock, and
choose Actions, Edit retention
rule lock.
-
In the Edit retention rule lock screen, choose
Lock, and then for Unlock
delay period, specify the unlock delay period in
days.
-
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
-
Open the Recycle Bin console at
https://console.amazonaws.cn/rbin/home/
-
In the navigation panel, choose Retention rules.
-
In the grid, select the locked retention rule to unlock, and choose
Actions, Edit retention rule lock.
-
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
-
Open the Recycle Bin console at https://console.amazonaws.cn/rbin/home/
-
In the navigation pane, choose Retention rules.
-
Select the retention rule to tag, choose the Tags tab,
and then choose Manage tags.
-
Choose Add tag. For Key, enter the
tag key. For Value, enter the tag value.
-
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
-
Open the Recycle Bin console at https://console.amazonaws.cn/rbin/home/
-
In the navigation pane, choose Retention rules.
-
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
-
Open the Recycle Bin console at https://console.amazonaws.cn/rbin/home/
-
In the navigation pane, choose Retention rules.
-
Select the retention rule from which to remove the tag, choose the Tags
tab, and then choose Manage tags.
-
Choose Remove next to the tag to remove.
-
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
-
Open the Recycle Bin console at https://console.amazonaws.cn/rbin/home/
-
In the navigation pane, choose Retention rules.
-
In the grid, select the retention rule to delete, and choose
Actions, Delete retention
rule.
-
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