Skip to content

Commit 28e4646

Browse files
jonesphillipOxyjun
jonesphillip
and
Oxyjun
authored
Document wrangler r2 lock command (list, add, remove, set) (#19846)
* Document wrangler r2 lock command (list, add, remove, set) * Document wrangler r2 lock command (list, add, remove, set) * Updated R2 bucket lock docs to mention wrangler commands. Fixed typo. * Added sections to R2 bucket lock docs for listing and removing rules * Update src/content/docs/r2/buckets/bucket-locks.mdx * Updates r2 lock command parameters --------- Co-authored-by: Jun Lee <[email protected]>
1 parent acf3d04 commit 28e4646

File tree

2 files changed

+183
-22
lines changed

2 files changed

+183
-22
lines changed

‎src/content/docs/r2/buckets/bucket-locks.mdx‎

Lines changed: 51 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -7,20 +7,34 @@ Bucket locks prevent the deletion and overwriting of objects in an R2 bucket for
77

88
## Get started with bucket locks
99

10-
### Prerequisites
11-
1210
Before getting started, you will need:
1311

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

17-
:::note
15+
### Enable bucket lock via Wrangler
1816

19-
Currently, Bucket locks are only configurable via API.
20-
:::
17+
1. Install [`npm`](https://docs.npmjs.com/getting-started).
18+
2. Install [Wrangler, the Developer Platform CLI](/workers/wrangler/install-and-update/).
19+
3. Log in to Wrangler with the [`wrangler login` command](/workers/wrangler/commands/#login).
20+
4. Add a bucket lock rule to your bucket by running the [`r2 bucket lock add` command](/workers/wrangler/commands/#r2-bucket-lock-add).
21+
22+
```sh
23+
npx wrangler r2 bucket lock add <BUCKET_NAME> [OPTIONS]
24+
```
25+
26+
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).
27+
28+
```sh
29+
npx wrangler r2 bucket lock set <BUCKET_NAME> --file <FILE_PATH>
30+
```
31+
32+
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/).
2133

2234
### Enable bucket lock via API
2335

36+
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/).
37+
2438
Below is an example of setting a bucket lock configuration (a collection of rules):
2539

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

58-
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/).
72+
:::note
73+
74+
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`.
75+
76+
:::
77+
78+
## Get bucket lock rules for your R2 bucket
5979

60-
### Get bucket lock rules via API
80+
### Wrangler
81+
82+
To list bucket lock rules, run the [`r2 bucket lock list` command](/workers/wrangler/commands/#r2-bucket-lock-list):
83+
84+
```sh
85+
npx wrangler r2 bucket lock list <BUCKET_NAME>
86+
```
87+
88+
### API
6189

6290
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/).
6391

92+
## Remove bucket lock rules from your R2 bucket
93+
94+
### Wrangler
95+
96+
To remove a bucket lock rule, run the [`r2 bucket lock remove` command](/workers/wrangler/commands/#r2-bucket-lock-remove):
97+
98+
```sh
99+
npx wrangler r2 bucket lock remove <BUCKET_NAME> --id <RULE_ID>
100+
```
101+
102+
### API
103+
104+
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/).
105+
64106
## Bucket lock rules
65107

66-
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:
108+
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:
67109

68110
- Lock objects for a specific duration. For example, 90 days.
69111
- Retain objects until a certain date. For example, until January 1, 2026.

‎src/content/partials/workers/wrangler-commands/r2.mdx‎

Lines changed: 132 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,11 @@ wrangler r2 bucket cors list <NAME> [OPTIONS]
107107
- `--jurisdiction` <Type text="string" /> <MetaInfo text="optional" />
108108
- The jurisdiction where the bucket exists, if a jurisdiction has been specified. Refer to [jurisdictional restrictions](/r2/reference/data-location/#jurisdictional-restrictions).
109109

110-
<AnchorHeading title="`dev-url enable`" slug="r2-bucket-dev-url-enable" depth={3} />
110+
<AnchorHeading
111+
title="`dev-url enable`"
112+
slug="r2-bucket-dev-url-enable"
113+
depth={3}
114+
/>
111115

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

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

125-
<AnchorHeading title="`dev-url disable`" slug="r2-bucket-dev-url-disable" depth={3} />
129+
<AnchorHeading
130+
title="`dev-url disable`"
131+
slug="r2-bucket-dev-url-disable"
132+
depth={3}
133+
/>
126134

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

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

174-
<AnchorHeading title="`domain remove`" slug="r2-bucket-domain-remove" depth={3} />
182+
<AnchorHeading
183+
title="`domain remove`"
184+
slug="r2-bucket-domain-remove"
185+
depth={3}
186+
/>
175187

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

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

191-
<AnchorHeading title="`domain update`" slug="r2-bucket-domain-update" depth={3} />
203+
<AnchorHeading
204+
title="`domain update`"
205+
slug="r2-bucket-domain-update"
206+
depth={3}
207+
/>
192208

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

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

236-
<AnchorHeading title="`lifecycle add`" slug="r2-bucket-lifecycle-add" depth={3} />
252+
<AnchorHeading
253+
title="`lifecycle add`"
254+
slug="r2-bucket-lifecycle-add"
255+
depth={3}
256+
/>
237257

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

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

265-
<AnchorHeading title="`lifecycle remove`" slug="r2-bucket-lifecycle-remove" depth={3} />
285+
<AnchorHeading
286+
title="`lifecycle remove`"
287+
slug="r2-bucket-lifecycle-remove"
288+
depth={3}
289+
/>
266290

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

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

280-
<AnchorHeading title="`lifecycle list`" slug="r2-bucket-lifecycle-list" depth={3} />
304+
<AnchorHeading
305+
title="`lifecycle list`"
306+
slug="r2-bucket-lifecycle-list"
307+
depth={3}
308+
/>
281309

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

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

293-
<AnchorHeading title="`lifecycle set`" slug="r2-bucket-lifecycle-set" depth={3} />
321+
<AnchorHeading
322+
title="`lifecycle set`"
323+
slug="r2-bucket-lifecycle-set"
324+
depth={3}
325+
/>
294326

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

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

310-
<AnchorHeading title="`notification create`" slug="r2-bucket-notification-create" depth={3} />
342+
<AnchorHeading title="`lock add`" slug="r2-bucket-lock-add" depth={3} />
343+
344+
Add a [bucket lock](/r2/buckets/bucket-locks/) rule to an R2 bucket.
345+
346+
```txt
347+
wrangler r2 bucket lock add <NAME> [OPTIONS]
348+
```
349+
350+
- `NAME` <Type text="string" /> <MetaInfo text="required" />
351+
- The name of the R2 bucket to add a bucket lock rule to.
352+
- `--id` <Type text="string" /> <MetaInfo text="optional" />
353+
- A unique identifier for the bucket lock rule.
354+
- `--prefix` <Type text="string" /> <MetaInfo text="optional" />
355+
- Prefix condition for the bucket lock rule (leave empty for all prefixes).
356+
- `--retention-days` <Type text="number" /> <MetaInfo text="optional" />
357+
- Sets the number of days to retain objects for. Note you can provide only one of `--retention-days`, `--retention-date`, or `--retention-indefinite`.
358+
- `--retention-date` <Type text="string" /> <MetaInfo text="optional" />
359+
- Sets the number of days to retain objects for. Note you can provide only one of `--retention-days`, `--retention-date`, or `--retention-indefinite`.
360+
- `--retention-indefinite` <Type text="string" /> <MetaInfo text="optional" />
361+
- 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`.
362+
- `--jurisdiction` <Type text="string" /> <MetaInfo text="optional" />
363+
- The jurisdiction where the bucket exists, if a jurisdiction has been specified. Refer to [jurisdictional restrictions](/r2/reference/data-location/#jurisdictional-restrictions).
364+
- `--force` <Type text="boolean" /> <MetaInfo text="optional" />
365+
- Skip confirmation when adding the bucket lock rule.
366+
367+
<AnchorHeading title="`lock remove`" slug="r2-bucket-lock-remove" depth={3} />
368+
369+
Remove a [bucket lock](/r2/buckets/bucket-locks/) rule from an R2 bucket.
370+
371+
```txt
372+
wrangler r2 bucket lock remove <NAME> [OPTIONS]
373+
```
374+
375+
- `NAME` <Type text="string" /> <MetaInfo text="required" />
376+
- The name of the R2 bucket to remove a bucket lock rule from.
377+
- `--id` <Type text="string" /> <MetaInfo text="required" />
378+
- The unique identifier of the bucket lock rule to remove.
379+
- `--jurisdiction` <Type text="string" /> <MetaInfo text="optional" />
380+
- The jurisdiction where the bucket exists, if a jurisdiction has been specified. Refer to [jurisdictional restrictions](/r2/reference/data-location/#jurisdictional-restrictions).
381+
382+
<AnchorHeading title="`lock list`" slug="r2-bucket-lock-list" depth={3} />
383+
384+
List [bucket lock](/r2/buckets/bucket-locks/) rules for an R2 bucket.
385+
386+
```txt
387+
wrangler r2 bucket lock list <NAME> [OPTIONS]
388+
```
389+
390+
- `NAME` <Type text="string" /> <MetaInfo text="required" />
391+
- The name of the R2 bucket to list bucket locks rules for.
392+
- `--jurisdiction` <Type text="string" /> <MetaInfo text="optional" />
393+
- The jurisdiction where the bucket exists, if a jurisdiction has been specified. Refer to [jurisdictional restrictions](/r2/reference/data-location/#jurisdictional-restrictions).
394+
395+
<AnchorHeading title="`lock set`" slug="r2-bucket-lock-set" depth={3} />
396+
397+
Set the [bucket lock](/r2/buckets/bucket-locks/) configuration for an R2 bucket from a JSON file.
398+
399+
```txt
400+
wrangler r2 bucket lock set <NAME> [OPTIONS]
401+
```
402+
403+
- `NAME` <Type text="string" /> <MetaInfo text="required" />
404+
- The name of the R2 bucket to set bucket lock configuration for.
405+
- `--file` <Type text="string" /> <MetaInfo text="required" />
406+
- 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/)).
407+
- `--jurisdiction` <Type text="string" /> <MetaInfo text="optional" />
408+
- The jurisdiction where the bucket exists, if a jurisdiction has been specified. Refer to [jurisdictional restrictions](/r2/reference/data-location/#jurisdictional-restrictions).
409+
- `--force` <Type text="boolean" /> <MetaInfo text="optional" />
410+
- Skip confirmation when setting bucket lock configuration.
411+
412+
<AnchorHeading
413+
title="`notification create`"
414+
slug="r2-bucket-notification-create"
415+
depth={3}
416+
/>
311417

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

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

331-
<AnchorHeading title="`notification delete`" slug="r2-bucket-notification-delete" depth={3} />
437+
<AnchorHeading
438+
title="`notification delete`"
439+
slug="r2-bucket-notification-delete"
440+
depth={3}
441+
/>
332442

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

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

346-
<AnchorHeading title="`notification list`" slug="r2-bucket-notification-list" depth={3} />
456+
<AnchorHeading
457+
title="`notification list`"
458+
slug="r2-bucket-notification-list"
459+
depth={3}
460+
/>
347461

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

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

393-
<AnchorHeading title="`sippy disable`" slug="r2-bucket-sippy-disable" depth={3} />
507+
<AnchorHeading
508+
title="`sippy disable`"
509+
slug="r2-bucket-sippy-disable"
510+
depth={3}
511+
/>
394512

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

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

485603
:::note
604+
486605
<Render file="wrangler-commands/global-flags" product="workers" />
487-
:::
606+
:::

0 commit comments

Comments
 (0)