diff --git a/src/content/docs/r2/buckets/bucket-locks.mdx b/src/content/docs/r2/buckets/bucket-locks.mdx index b3c8cd09a761463..e14a9ce60f1ae5f 100644 --- a/src/content/docs/r2/buckets/bucket-locks.mdx +++ b/src/content/docs/r2/buckets/bucket-locks.mdx @@ -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 [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 --file +``` + +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 @@ -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 +``` + +### 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 --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. diff --git a/src/content/partials/workers/wrangler-commands/r2.mdx b/src/content/partials/workers/wrangler-commands/r2.mdx index d1dc42b5fad852a..d344f3959e3deee 100644 --- a/src/content/partials/workers/wrangler-commands/r2.mdx +++ b/src/content/partials/workers/wrangler-commands/r2.mdx @@ -107,7 +107,11 @@ wrangler r2 bucket cors list [OPTIONS] - `--jurisdiction` - The jurisdiction where the bucket exists, if a jurisdiction has been specified. Refer to [jurisdictional restrictions](/r2/reference/data-location/#jurisdictional-restrictions). - + Enable public access via the [r2.dev URL](/r2/buckets/public-buckets/#enable-managed-public-access) for an R2 bucket. @@ -122,7 +126,11 @@ wrangler r2 bucket dev-url enable [OPTIONS] - `--force` - Skip confirmation when enabling public access via r2.dev URL. - + Disable public access via the [r2.dev URL](/r2/buckets/public-buckets/#enable-managed-public-access) for an R2 bucket. @@ -171,7 +179,11 @@ wrangler r2 bucket domain add [OPTIONS] - `--force` - Skip confirmation when adding the custom domain. - + Remove a [custom domain](/r2/buckets/public-buckets/#custom-domains) from an R2 bucket. @@ -188,7 +200,11 @@ wrangler r2 bucket domain remove [OPTIONS] - `--force` - Skip confirmation when removing the custom domain. - + Update settings for a [custom domain](/r2/buckets/public-buckets/#custom-domains) connected to an R2 bucket. @@ -233,7 +249,11 @@ wrangler r2 bucket domain list [OPTIONS] - `--jurisdiction` - The jurisdiction where the bucket exists, if a jurisdiction has been specified. Refer to [jurisdictional restrictions](/r2/reference/data-location/#jurisdictional-restrictions). - + Add an [object lifecycle](/r2/buckets/object-lifecycles/) rule to an R2 bucket. @@ -262,7 +282,11 @@ wrangler r2 bucket lifecycle add [OPTIONS] - `--force` - Skip confirmation when adding the lifecycle rule. - + Remove an [object lifecycle](/r2/buckets/object-lifecycles/) rule from an R2 bucket. @@ -277,7 +301,11 @@ wrangler r2 bucket lifecycle remove [OPTIONS] - `--jurisdiction` - The jurisdiction where the bucket exists, if a jurisdiction has been specified. Refer to [jurisdictional restrictions](/r2/reference/data-location/#jurisdictional-restrictions). - + List [object lifecycle](/r2/buckets/object-lifecycles/) rules for an R2 bucket. @@ -290,7 +318,11 @@ wrangler r2 bucket lifecycle list [OPTIONS] - `--jurisdiction` - The jurisdiction where the bucket exists, if a jurisdiction has been specified. Refer to [jurisdictional restrictions](/r2/reference/data-location/#jurisdictional-restrictions). - + Set the [object lifecycle](/r2/buckets/object-lifecycles/) configuration for an R2 bucket from a JSON file. @@ -307,7 +339,81 @@ wrangler r2 bucket lifecycle set [OPTIONS] - `--force` - Skip confirmation when setting object lifecycle configuration. - + + +Add a [bucket lock](/r2/buckets/bucket-locks/) rule to an R2 bucket. + +```txt +wrangler r2 bucket lock add [OPTIONS] +``` + +- `NAME` + - The name of the R2 bucket to add a bucket lock rule to. +- `--id` + - A unique identifier for the bucket lock rule. +- `--prefix` + - Prefix condition for the bucket lock rule (leave empty for all prefixes). +- `--retention-days` + - 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` + - 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` + - 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` + - The jurisdiction where the bucket exists, if a jurisdiction has been specified. Refer to [jurisdictional restrictions](/r2/reference/data-location/#jurisdictional-restrictions). +- `--force` + - Skip confirmation when adding the bucket lock rule. + + + +Remove a [bucket lock](/r2/buckets/bucket-locks/) rule from an R2 bucket. + +```txt +wrangler r2 bucket lock remove [OPTIONS] +``` + +- `NAME` + - The name of the R2 bucket to remove a bucket lock rule from. +- `--id` + - The unique identifier of the bucket lock rule to remove. +- `--jurisdiction` + - The jurisdiction where the bucket exists, if a jurisdiction has been specified. Refer to [jurisdictional restrictions](/r2/reference/data-location/#jurisdictional-restrictions). + + + +List [bucket lock](/r2/buckets/bucket-locks/) rules for an R2 bucket. + +```txt +wrangler r2 bucket lock list [OPTIONS] +``` + +- `NAME` + - The name of the R2 bucket to list bucket locks rules for. +- `--jurisdiction` + - The jurisdiction where the bucket exists, if a jurisdiction has been specified. Refer to [jurisdictional restrictions](/r2/reference/data-location/#jurisdictional-restrictions). + + + +Set the [bucket lock](/r2/buckets/bucket-locks/) configuration for an R2 bucket from a JSON file. + +```txt +wrangler r2 bucket lock set [OPTIONS] +``` + +- `NAME` + - The name of the R2 bucket to set bucket lock configuration for. +- `--file` + - 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` + - The jurisdiction where the bucket exists, if a jurisdiction has been specified. Refer to [jurisdictional restrictions](/r2/reference/data-location/#jurisdictional-restrictions). +- `--force` + - Skip confirmation when setting bucket lock configuration. + + Create an [event notification](/r2/buckets/event-notifications/) rule for an R2 bucket. @@ -328,7 +434,11 @@ wrangler r2 bucket notification create [OPTIONS] - `--description` - A description that can be used to identify the event notification rule after creation. - + Remove an event notification rule from a bucket's [event notification](/r2/buckets/event-notifications/) configuration. @@ -343,7 +453,11 @@ wrangler r2 bucket notification delete [OPTIONS] - `--rule` - The ID of the event notification rule to delete. - + List the [event notification](/r2/buckets/event-notifications/) rules for a bucket. @@ -390,7 +504,11 @@ wrangler r2 bucket sippy enable [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. - + Disable [Sippy](/r2/data-migration/sippy/) incremental migration for a bucket. @@ -483,5 +601,6 @@ wrangler r2 object delete [OPTIONS] - Specify directory for locally persisted data. :::note + -::: \ No newline at end of file +:::