Bucket locks

Model-written

contextmethodsetupresultanalysislimitation

Bucket locks prevent the deletion and overwriting of objects in an R2 bucket for a specified period — or indefinitely. When enabled, bucket locks enforce retention policies on your objects, helping protect them from accidental or premature deletions.Bucket locks prevent the deletion and overwriting of objects in an R2 bucket for a specified period — or indefinitely. When enabled, bucket locks enforce retention policies on your objects, helping protect them from accidental or premature deletions.Bucket locks prevent object deletion and overwriting for a set period or indefinitely Enforced retention policies protect objects from accidental or premature deletionBucket locks prevent object deletion and overwriting for a set period or indefinitelyBucket locks

Get started with bucket locks

You need an existing bucket and, for API, an API token

Before getting started, you will need:Before getting started, you will need:Getting started requires prerequisites firstGetting started requires prerequisites firstprerequisites

An existing R2 bucket. If you do not already have an existing R2 bucket, refer to Create buckets.
An existing R2 bucket.
An existing R2 bucket is required Refer to Create buckets if you do not already have one
An existing R2 bucket is required
R2 bucket
(API only) An API token with permissions to edit R2 bucket configuration.
(API only) An API token with permissions to edit R2 bucket configuration.
API users need a token with R2 bucket configuration edit permissions
API users need a token with R2 bucket configuration edit permissions
API token

Enable bucket lock via dashboard

Add a lock rule in the dashboard Settings tab and save

In the Cloudflare dashboard, go to the R2 object storage page.

dash.cloudflare.com
Select the bucket you would like to add bucket lock rule to.
Switch to the Settings tab, then scroll down to the Bucket lock rules card.
Select Add rule and enter the rule name, prefix, and retention period.
Select Save changes.

Enable bucket lock via Wrangler

Use r2 bucket lock add or set a JSON configuration file

Install npm.
Install Wrangler, the Developer Platform CLI.
Log in to Wrangler with the wrangler login command.
Add a bucket lock rule to your bucket by running the r2 bucket lock add command.
Add a bucket lock rule to your bucket by running the r2 bucket lock add command.
Add a lock rule with r2 bucket lock add
Add a lock rule with r2 bucket lock add
lock add

npx wrangler r2 bucket lock add <BUCKET_NAME> [OPTIONS]

Alternatively, you can set the entire bucket lock configuration for a bucket from a JSON file using the r2 bucket lock set command.Alternatively, you can set the entire bucket lock configuration for a bucket from a JSON file using the r2 bucket lock set command.Set the whole lock configuration from a JSON file with r2 bucket lock setSet the whole lock configuration from a JSON file with r2 bucket lock setlock set

npx wrangler r2 bucket lock set <BUCKET_NAME> --file <FILE_PATH>

The JSON file should be in the format of the request body of the put bucket lock configuration API.The JSON file should be in the format of the request body of the put bucket lock configuration API.The JSON file must match the put bucket lock configuration request bodyThe JSON file must match the put bucket lock configuration request bodyJSON format

Enable bucket lock via API

PUT the bucket lock endpoint with a rules array

For information about getting started with the Cloudflare API, refer to Make API calls. For information on required parameters and more examples of how to set bucket lock configuration, refer to the API documentation.For information about getting started with the Cloudflare API, refer to Make API calls. For information on required parameters and more examples of how to set bucket lock configuration, refer to the API documentation.API getting started and parameters are covered in linked docsAPI getting started and parameters are covered in linked docsAPI docs

Below is an example of setting a bucket lock configuration (a collection of rules):Below is an example of setting a bucket lock configuration (a collection of rules):A lock configuration is a collection of rules set via PUTA lock configuration is a collection of rules set via PUTconfiguration

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/r2/buckets/<BUCKET_NAME>/lock" \
    -H "Authorization: Bearer <API_TOKEN>" \
    -H "Content-Type: application/json" \
    -d '{
        "rules": [
            {
                "id": "lock-logs-7d",
                "enabled": true,
                "prefix": "logs/",
                "condition": {
                    "type": "Age",
                    "maxAgeSeconds": 604800
                }
            },
            {
                "id": "lock-images-indefinite",
                "enabled": true,
                "prefix": "images/",
                "condition": {
                    "type": "Indefinite"
                }
            }
        ]
    }'

This request creates two rules:This request creates two rules:The request creates two rulesThe request creates two rulestwo rules

lock-logs-7d: Objects under the logs/ prefix are retained for 7 days (604800 seconds).
lock-logs-7d: Objects under the logs/ prefix are retained for 7 days (604800 seconds).
lock-logs-7d retains logs/ objects for 7 days 604800 seconds equals seven days
lock-logs-7d retains logs/ objects for 7 days
lock-logs-7d
lock-images-indefinite: Objects under the images/ prefix are locked indefinitely.
lock-images-indefinite: Objects under the images/ prefix are locked indefinitely.
lock-images-indefinite locks images/ objects indefinitely
lock-images-indefinite locks images/ objects indefinitely
lock-images-indefinite

Note

If your bucket is setup with jurisdictional restrictions, you will need to pass a cf-r2-jurisdiction request header with that jurisdiction. For example, cf-r2-jurisdiction: eu.If your bucket is setup with jurisdictional restrictions, you will need to pass a cf-r2-jurisdiction request header with that jurisdiction. For example, cf-r2-jurisdiction: eu.Jurisdictional buckets require a cf-r2-jurisdiction request header For example, pass cf-r2-jurisdiction: eu for the EU jurisdictionJurisdictional buckets require a cf-r2-jurisdiction request headercf-r2-jurisdiction

Get bucket lock rules for your R2 bucket

Dashboard

View lock rules in the Settings tab Bucket lock rules card

In the Cloudflare dashboard, go to the R2 object storage page.

dash.cloudflare.com
Select the bucket you would like to add bucket lock rule to.
Switch to the Settings tab, then scroll down to the Bucket lock rules card.

Wrangler

List rules with r2 bucket lock list

To list bucket lock rules, run the r2 bucket lock list command:To list bucket lock rules, run the r2 bucket lock list command:List lock rules with r2 bucket lock listList lock rules with r2 bucket lock listlock list

npx wrangler r2 bucket lock list <BUCKET_NAME>

API

Get rules via the API documentation endpoint

For more information on required parameters and examples of how to get bucket lock rules, refer to the API documentation.For more information on required parameters and examples of how to get bucket lock rules, refer to the API documentation.Getting lock rules via API is documented in the API referenceGetting lock rules via API is documented in the API referenceAPI reference

Remove bucket lock rules from your R2 bucket

Dashboard

Delete a rule from the Settings tab via the ... icon

In the Cloudflare dashboard, go to the R2 object storage page.

dash.cloudflare.com
Select the bucket you would like to add bucket lock rule to.
Switch to the Settings tab, then scroll down to the Bucket lock rules card.
Locate the rule you want to remove, select the ... icon next to it, and then select Delete.

Locate the rule you want to remove, select the ... icon next to it, and then select Delete.
Delete a rule via the ... icon next to it
Delete a rule via the ... icon next to it
... icon

Wrangler

Remove a rule with r2 bucket lock remove and its id

To remove a bucket lock rule, run the r2 bucket lock remove command:To remove a bucket lock rule, run the r2 bucket lock remove command:Remove a rule with r2 bucket lock remove and its idRemove a rule with r2 bucket lock remove and its idlock remove

npx wrangler r2 bucket lock remove <BUCKET_NAME> --id <RULE_ID>

API

Exclude rules from the updated configuration to remove them

To remove bucket lock rules via API, exclude them from your updated configuration and use the put bucket lock configuration API.To remove bucket lock rules via API, exclude them from your updated configuration and use the put bucket lock configuration API.To remove rules via API, exclude them from the updated configuration The put bucket lock configuration API replaces rules absent from the new configurationTo remove rules via API, exclude them from the updated configurationupdated configuration

Bucket lock rules

Up to 1,000 rules; strictest retention wins

A bucket lock configuration can include up to 1,000 rules. Each rule specifies which objects it covers (via prefix) and how long those objects must remain locked. You can:A bucket lock configuration can include up to 1,000 rules. Each rule specifies which objects it covers (via prefix) and how long those objects must remain locked.A configuration holds up to 1,000 rules, each with prefix and durationA configuration holds up to 1,000 rules, each with prefix and duration1,000 rules

Lock objects for a specific duration. For example, 90 days.
Lock objects for a specific duration.
Rules can lock objects for a specific duration For example, 90 days
Rules can lock objects for a specific duration
specific duration
Retain objects until a certain date. For example, until January 1, 2026.
Retain objects until a certain date.
Rules can retain objects until a certain date For example, until January 1, 2026
Rules can retain objects until a certain date
certain date
Keep objects locked indefinitely.
Keep objects locked indefinitely.
Rules can keep objects locked indefinitely
Rules can keep objects locked indefinitely
locked indefinitely

If multiple rules apply to the same prefix or object key, the strictest (longest) retention requirement takes precedence.If multiple rules apply to the same prefix or object key, the strictest (longest) retention requirement takes precedence.The strictest longest retention requirement takes precedence on overlap This resolves conflicts when multiple rules apply to the same prefix or keyThe strictest longest retention requirement takes precedence on overlapstrictest retention

Notes

Locks override lifecycle rules and block bucket emptying

Rules without prefix apply to all objects in the bucket.
Rules without prefix apply to all objects in the bucket.
Rules without a prefix apply to all bucket objects
Rules without a prefix apply to all bucket objects
all objects
Rules apply to both new and existing objects in the bucket.
Rules apply to both new and existing objects in the bucket.
Rules apply to both new and existing objects
Rules apply to both new and existing objects
existing objects
Bucket lock rules take precedence over lifecycle rules. For example, if a lifecycle rule attempts to delete an object at 30 days but a bucket lock rule requires it be retained for 90 days, the object will not be deleted until the 90-day requirement is met.
Bucket lock rules take precedence over lifecycle rules. For example, if a lifecycle rule attempts to delete an object at 30 days but a bucket lock rule requires it be retained for 90 days, the object will not be deleted until the 90-day requirement is met.
Bucket lock rules take precedence over lifecycle rules An object due at 30 days stays until the 90-day lock is met
Bucket lock rules take precedence over lifecycle rules
lifecycle rules
A bucket cannot be emptied while any bucket lock rules are configured. Remove all lock rules before emptying a bucket. Bucket lock rules also apply when deleting folders from the dashboard.
A bucket cannot be emptied while any bucket lock rules are configured. Remove all lock rules before emptying a bucket.
A bucket cannot be emptied while lock rules exist Rules also apply when deleting folders from the dashboard
A bucket cannot be emptied while lock rules exist
emptying a bucket

Key points (written by a model)

Get started with bucket locks

Enable bucket lock via dashboard

Enable bucket lock via Wrangler

Enable bucket lock via API

Get bucket lock rules for your R2 bucket

Dashboard

Wrangler

API

Remove bucket lock rules from your R2 bucket

Dashboard

Wrangler

API

Bucket lock rules

Notes