Skip to content

Document wrangler r2 lock command (list, add, remove, set) #19846

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Mar 5, 2025
Merged

Document wrangler r2 lock command (list, add, remove, set) #19846

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
0ca5b07
Document wrangler r2 lock command (list, add, remove, set)
jonesphillip Feb 7, 2025
3258f60
Document wrangler r2 lock command (list, add, remove, set)
jonesphillip Feb 7, 2025
01b17d4
Updated R2 bucket lock docs to mention wrangler commands. Fixed typo.
jonesphillip Feb 12, 2025
6b7af22
Added sections to R2 bucket lock docs for listing and removing rules
jonesphillip Feb 12, 2025
4ad44a0
Update src/content/docs/r2/buckets/bucket-locks.mdx
Oxyjun Feb 12, 2025
cbd9499
Merge branch 'pjones/wrangler-bucket-lock-docs' of github.com:cloudfl…
Oxyjun Feb 12, 2025
351bdcb
Merge commit '01364359ccb7f54f46d95aa3c715de52062b5605' into pjones/w…
Oxyjun Feb 12, 2025
02f6f00
Updates r2 lock command parameters
jonesphillip Feb 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 51 additions & 9 deletions src/content/docs/r2/buckets/bucket-locks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,20 +7,34 @@ Bucket locks prevent the deletion and overwriting of objects in an R2 bucket for

## Get started with bucket locks

### Prerequisites

Before getting started, you will need:

- An existing R2 bucket. If you do not already have an existing R2 bucket, refer to [Create buckets](/r2/buckets/create-buckets/).
- An API token with [permissions](/r2/api/s3/tokens/#permissions) to edit R2 bucket configuration.
- (API only) An API token with [permissions](/r2/api/s3/tokens/#permissions) to edit R2 bucket configuration.

:::note
### Enable bucket lock via Wrangler

Currently, Bucket locks are only configurable via API.
:::
1. Install [`npm`](https://docs.npmjs.com/getting-started).
2. Install [Wrangler, the Developer Platform CLI](/workers/wrangler/install-and-update/).
3. Log in to Wrangler with the [`wrangler login` command](/workers/wrangler/commands/#login).
4. Add a bucket lock rule to your bucket by running the [`r2 bucket lock add` command](/workers/wrangler/commands/#r2-bucket-lock-add).

```sh
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](/workers/wrangler/commands/#r2-bucket-lock-set).

```sh
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](/api/resources/r2/subresources/buckets/subresources/locks/methods/update/).

### Enable bucket lock via API

For information about getting started with the Cloudflare API, refer to [Make API calls](/fundamentals/api/how-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/resources/r2/subresources/buckets/subresources/locks/methods/update/).

Below is an example of setting a bucket lock configuration (a collection of rules):

```bash
Expand Down Expand Up @@ -55,15 +69,43 @@ This request creates two rules:
- `lock-logs-7d`: Objects under the `logs/` prefix are retained for 7 days (604800 seconds).
- `lock-images-indefinite`: Objects under the `images/` prefix are locked indefinitely.

For more information on required parameters and examples of how to enable bucket lock, refer to the [API documentation](/api/resources/r2/subresources/buckets/subresources/locks/methods/update/). For information about getting started with the Cloudflare API, refer to [Make API calls](/fundamentals/api/how-to/make-api-calls/).
:::note

If your bucket is setup with [jurisdictional restrictions](/r2/reference/data-location/#jurisdictional-restrictions), you will need to pass a `cf-r2-jurisdiction` request header with that jurisdiction. For example, `cf-r2-jurisdiction: eu`.

:::

## Get bucket lock rules for your R2 bucket

### Get bucket lock rules via API
### Wrangler

To list bucket lock rules, run the [`r2 bucket lock list` command](/workers/wrangler/commands/#r2-bucket-lock-list):

```sh
npx wrangler r2 bucket lock list <BUCKET_NAME>
```

### API

For more information on required parameters and examples of how to get bucket lock rules, refer to the [API documentation](/api/resources/r2/subresources/buckets/subresources/locks/methods/get/).

## Remove bucket lock rules from your R2 bucket

### Wrangler

To remove a bucket lock rule, run the [`r2 bucket lock remove` command](/workers/wrangler/commands/#r2-bucket-lock-remove):

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

### API

To remove bucket lock rules via API, exclude them from your updated configuration and use the [put bucket lock configuration API](/api/resources/r2/subresources/buckets/subresources/locks/methods/update/).

## Bucket lock rules

A bucket lock configuration can include up to 1,000 rules. Each rule specifies which object 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. You can:

- Lock objects for a specific duration. For example, 90 days.
- Retain objects until a certain date. For example, until January 1, 2026.
Expand Down
145 changes: 132 additions & 13 deletions src/content/partials/workers/wrangler-commands/r2.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,11 @@ wrangler r2 bucket cors list <NAME> [OPTIONS]
- `--jurisdiction` <Type text="string" /> <MetaInfo text="optional" />
- The jurisdiction where the bucket exists, if a jurisdiction has been specified. Refer to [jurisdictional restrictions](/r2/reference/data-location/#jurisdictional-restrictions).

<AnchorHeading title="`dev-url enable`" slug="r2-bucket-dev-url-enable" depth={3} />
<AnchorHeading
title="`dev-url enable`"
slug="r2-bucket-dev-url-enable"
depth={3}
/>

Enable public access via the [r2.dev URL](/r2/buckets/public-buckets/#enable-managed-public-access) for an R2 bucket.

Expand All @@ -122,7 +126,11 @@ wrangler r2 bucket dev-url enable <NAME> [OPTIONS]
- `--force` <Type text="boolean" /> <MetaInfo text="optional" />
- Skip confirmation when enabling public access via r2.dev URL.

<AnchorHeading title="`dev-url disable`" slug="r2-bucket-dev-url-disable" depth={3} />
<AnchorHeading
title="`dev-url disable`"
slug="r2-bucket-dev-url-disable"
depth={3}
/>

Disable public access via the [r2.dev URL](/r2/buckets/public-buckets/#enable-managed-public-access) for an R2 bucket.

Expand Down Expand Up @@ -171,7 +179,11 @@ wrangler r2 bucket domain add <NAME> [OPTIONS]
- `--force` <Type text="boolean" /> <MetaInfo text="optional" />
- Skip confirmation when adding the custom domain.

<AnchorHeading title="`domain remove`" slug="r2-bucket-domain-remove" depth={3} />
<AnchorHeading
title="`domain remove`"
slug="r2-bucket-domain-remove"
depth={3}
/>

Remove a [custom domain](/r2/buckets/public-buckets/#custom-domains) from an R2 bucket.

Expand All @@ -188,7 +200,11 @@ wrangler r2 bucket domain remove <NAME> [OPTIONS]
- `--force` <Type text="boolean" /> <MetaInfo text="optional" />
- Skip confirmation when removing the custom domain.

<AnchorHeading title="`domain update`" slug="r2-bucket-domain-update" depth={3} />
<AnchorHeading
title="`domain update`"
slug="r2-bucket-domain-update"
depth={3}
/>

Update settings for a [custom domain](/r2/buckets/public-buckets/#custom-domains) connected to an R2 bucket.

Expand Down Expand Up @@ -233,7 +249,11 @@ wrangler r2 bucket domain list <NAME> [OPTIONS]
- `--jurisdiction` <Type text="string" /> <MetaInfo text="optional" />
- The jurisdiction where the bucket exists, if a jurisdiction has been specified. Refer to [jurisdictional restrictions](/r2/reference/data-location/#jurisdictional-restrictions).

<AnchorHeading title="`lifecycle add`" slug="r2-bucket-lifecycle-add" depth={3} />
<AnchorHeading
title="`lifecycle add`"
slug="r2-bucket-lifecycle-add"
depth={3}
/>

Add an [object lifecycle](/r2/buckets/object-lifecycles/) rule to an R2 bucket.

Expand Down Expand Up @@ -262,7 +282,11 @@ wrangler r2 bucket lifecycle add <NAME> [OPTIONS]
- `--force` <Type text="boolean" /> <MetaInfo text="optional" />
- Skip confirmation when adding the lifecycle rule.

<AnchorHeading title="`lifecycle remove`" slug="r2-bucket-lifecycle-remove" depth={3} />
<AnchorHeading
title="`lifecycle remove`"
slug="r2-bucket-lifecycle-remove"
depth={3}
/>

Remove an [object lifecycle](/r2/buckets/object-lifecycles/) rule from an R2 bucket.

Expand All @@ -277,7 +301,11 @@ wrangler r2 bucket lifecycle remove <NAME> [OPTIONS]
- `--jurisdiction` <Type text="string" /> <MetaInfo text="optional" />
- The jurisdiction where the bucket exists, if a jurisdiction has been specified. Refer to [jurisdictional restrictions](/r2/reference/data-location/#jurisdictional-restrictions).

<AnchorHeading title="`lifecycle list`" slug="r2-bucket-lifecycle-list" depth={3} />
<AnchorHeading
title="`lifecycle list`"
slug="r2-bucket-lifecycle-list"
depth={3}
/>

List [object lifecycle](/r2/buckets/object-lifecycles/) rules for an R2 bucket.

Expand All @@ -290,7 +318,11 @@ wrangler r2 bucket lifecycle list <NAME> [OPTIONS]
- `--jurisdiction` <Type text="string" /> <MetaInfo text="optional" />
- The jurisdiction where the bucket exists, if a jurisdiction has been specified. Refer to [jurisdictional restrictions](/r2/reference/data-location/#jurisdictional-restrictions).

<AnchorHeading title="`lifecycle set`" slug="r2-bucket-lifecycle-set" depth={3} />
<AnchorHeading
title="`lifecycle set`"
slug="r2-bucket-lifecycle-set"
depth={3}
/>

Set the [object lifecycle](/r2/buckets/object-lifecycles/) configuration for an R2 bucket from a JSON file.

Expand All @@ -307,7 +339,81 @@ wrangler r2 bucket lifecycle set <NAME> [OPTIONS]
- `--force` <Type text="boolean" /> <MetaInfo text="optional" />
- Skip confirmation when setting object lifecycle configuration.

<AnchorHeading title="`notification create`" slug="r2-bucket-notification-create" depth={3} />
<AnchorHeading title="`lock add`" slug="r2-bucket-lock-add" depth={3} />

Add a [bucket lock](/r2/buckets/bucket-locks/) rule to an R2 bucket.

```txt
wrangler r2 bucket lock add <NAME> [OPTIONS]
```

- `NAME` <Type text="string" /> <MetaInfo text="required" />
- The name of the R2 bucket to add a bucket lock rule to.
- `--id` <Type text="string" /> <MetaInfo text="optional" />
- A unique identifier for the bucket lock rule.
- `--prefix` <Type text="string" /> <MetaInfo text="optional" />
- Prefix condition for the bucket lock rule (leave empty for all prefixes).
- `--retention-days` <Type text="number" /> <MetaInfo text="optional" />
- Sets the number of days to retain objects for. Note you can provide only one of `--retention-days`, `--retention-date`, or `--retention-indefinite`.
- `--retention-date` <Type text="string" /> <MetaInfo text="optional" />
- Sets the number of days to retain objects for. Note you can provide only one of `--retention-days`, `--retention-date`, or `--retention-indefinite`.
- `--retention-indefinite` <Type text="string" /> <MetaInfo text="optional" />
- Sets the retention period to indefinite — meaning the lock will remain in place until explicitly removed. Note you can provide only one of `--retention-days`, `--retention-date`, or `--retention-indefinite`.
- `--jurisdiction` <Type text="string" /> <MetaInfo text="optional" />
- The jurisdiction where the bucket exists, if a jurisdiction has been specified. Refer to [jurisdictional restrictions](/r2/reference/data-location/#jurisdictional-restrictions).
- `--force` <Type text="boolean" /> <MetaInfo text="optional" />
- Skip confirmation when adding the bucket lock rule.

<AnchorHeading title="`lock remove`" slug="r2-bucket-lock-remove" depth={3} />

Remove a [bucket lock](/r2/buckets/bucket-locks/) rule from an R2 bucket.

```txt
wrangler r2 bucket lock remove <NAME> [OPTIONS]
```

- `NAME` <Type text="string" /> <MetaInfo text="required" />
- The name of the R2 bucket to remove a bucket lock rule from.
- `--id` <Type text="string" /> <MetaInfo text="required" />
- The unique identifier of the bucket lock rule to remove.
- `--jurisdiction` <Type text="string" /> <MetaInfo text="optional" />
- The jurisdiction where the bucket exists, if a jurisdiction has been specified. Refer to [jurisdictional restrictions](/r2/reference/data-location/#jurisdictional-restrictions).

<AnchorHeading title="`lock list`" slug="r2-bucket-lock-list" depth={3} />

List [bucket lock](/r2/buckets/bucket-locks/) rules for an R2 bucket.

```txt
wrangler r2 bucket lock list <NAME> [OPTIONS]
```

- `NAME` <Type text="string" /> <MetaInfo text="required" />
- The name of the R2 bucket to list bucket locks rules for.
- `--jurisdiction` <Type text="string" /> <MetaInfo text="optional" />
- The jurisdiction where the bucket exists, if a jurisdiction has been specified. Refer to [jurisdictional restrictions](/r2/reference/data-location/#jurisdictional-restrictions).

<AnchorHeading title="`lock set`" slug="r2-bucket-lock-set" depth={3} />

Set the [bucket lock](/r2/buckets/bucket-locks/) configuration for an R2 bucket from a JSON file.

```txt
wrangler r2 bucket lock set <NAME> [OPTIONS]
```

- `NAME` <Type text="string" /> <MetaInfo text="required" />
- The name of the R2 bucket to set bucket lock configuration for.
- `--file` <Type text="string" /> <MetaInfo text="required" />
- Path to the JSON file containing bucket lock configuration (file must be in format of request body of [put bucket lock configuration API](/api/resources/r2/subresources/buckets/subresources/locks/methods/update/)).
- `--jurisdiction` <Type text="string" /> <MetaInfo text="optional" />
- The jurisdiction where the bucket exists, if a jurisdiction has been specified. Refer to [jurisdictional restrictions](/r2/reference/data-location/#jurisdictional-restrictions).
- `--force` <Type text="boolean" /> <MetaInfo text="optional" />
- Skip confirmation when setting bucket lock configuration.

<AnchorHeading
title="`notification create`"
slug="r2-bucket-notification-create"
depth={3}
/>

Create an [event notification](/r2/buckets/event-notifications/) rule for an R2 bucket.

Expand All @@ -328,7 +434,11 @@ wrangler r2 bucket notification create <NAME> [OPTIONS]
- `--description` <Type text="string" /> <MetaInfo text="optional" />
- A description that can be used to identify the event notification rule after creation.

<AnchorHeading title="`notification delete`" slug="r2-bucket-notification-delete" depth={3} />
<AnchorHeading
title="`notification delete`"
slug="r2-bucket-notification-delete"
depth={3}
/>

Remove an event notification rule from a bucket's [event notification](/r2/buckets/event-notifications/) configuration.

Expand All @@ -343,7 +453,11 @@ wrangler r2 bucket notification delete <NAME> [OPTIONS]
- `--rule` <Type text="string" /> <MetaInfo text="optional" />
- The ID of the event notification rule to delete.

<AnchorHeading title="`notification list`" slug="r2-bucket-notification-list" depth={3} />
<AnchorHeading
title="`notification list`"
slug="r2-bucket-notification-list"
depth={3}
/>

List the [event notification](/r2/buckets/event-notifications/) rules for a bucket.

Expand Down Expand Up @@ -390,7 +504,11 @@ wrangler r2 bucket sippy enable <NAME> [OPTIONS]
- The private key for your Google Cloud service account key. Requires [read and list access](/r2/data-migration/sippy/#google-cloud-storage).
- Note that you must provide either `service-account-key-file` or `client_email` and `private_key` for this command to run successfully.

<AnchorHeading title="`sippy disable`" slug="r2-bucket-sippy-disable" depth={3} />
<AnchorHeading
title="`sippy disable`"
slug="r2-bucket-sippy-disable"
depth={3}
/>

Disable [Sippy](/r2/data-migration/sippy/) incremental migration for a bucket.

Expand Down Expand Up @@ -483,5 +601,6 @@ wrangler r2 object delete <OBJECT_PATH> [OPTIONS]
- Specify directory for locally persisted data.

:::note

<Render file="wrangler-commands/global-flags" product="workers" />
:::
:::
Loading