From 0627327fb82297256bbf4c9ee2c5eba30557a985 Mon Sep 17 00:00:00 2001 From: Angie Pinilla Date: Fri, 25 Feb 2022 10:11:51 -0500 Subject: [PATCH] docs/s3: additional details on object locking for existing buckets --- website/docs/r/s3_bucket.html.markdown | 5 +- ...et_object_lock_configuration.html.markdown | 47 +++++++++++++++++-- 2 files changed, 46 insertions(+), 6 deletions(-) diff --git a/website/docs/r/s3_bucket.html.markdown b/website/docs/r/s3_bucket.html.markdown index ee0185cd251..fc900885e5b 100644 --- a/website/docs/r/s3_bucket.html.markdown +++ b/website/docs/r/s3_bucket.html.markdown @@ -60,8 +60,9 @@ See the [`aws_s3_bucket_lifecycle_configuration` resource](s3_bucket_lifecycle_c ### Using object lock configuration The `object_lock_configuration.rule` argument is read-only as of version 4.0 of the Terraform AWS Provider. -To **enable** Object Lock on your bucket, use must still use the `object_lock_configuration.object_lock_enabled` argument in **this** resource. +To **enable** Object Lock on a **new** bucket, use the `object_lock_configuration.object_lock_enabled` argument in **this** resource. See [Object Lock Configuration](#object-lock-configuration) below for details. To configure the default retention rule of the Object Lock configuration, see the [`aws_s3_bucket_object_lock_configuration` resource](s3_bucket_object_lock_configuration.html.markdown) for configuration details. +To **enable** Object Lock on an **existing** bucket, please contact AWS Support and refer to the [Object lock configuration for an existing bucket](s3_bucket_object_lock_configuration.html.markdown#object-lock-configuration-for-an-existing-bucket) example for more details. ### Using replication configuration @@ -90,7 +91,7 @@ The following arguments are supported: ### Object Lock Configuration -~> **NOTE:** You can only enable S3 Object Lock for _new_ buckets. If you need to turn on S3 Object Lock for an _existing_ bucket, please contact AWS Support. +~> **NOTE:** You can only **enable** S3 Object Lock for **new** buckets. If you need to **enable** S3 Object Lock for an **existing** bucket, please contact AWS Support. When you create a bucket with S3 Object Lock enabled, Amazon S3 automatically enables versioning for the bucket. Once you create a bucket with S3 Object Lock enabled, you can't disable Object Lock or suspend versioning for the bucket. To configure the default retention rule of the Object Lock configuration, see the [`aws_s3_bucket_object_lock_configuration` resource](s3_bucket_object_lock_configuration.html.markdown) for configuration details. diff --git a/website/docs/r/s3_bucket_object_lock_configuration.html.markdown b/website/docs/r/s3_bucket_object_lock_configuration.html.markdown index 53c9205515d..25a2413784a 100644 --- a/website/docs/r/s3_bucket_object_lock_configuration.html.markdown +++ b/website/docs/r/s3_bucket_object_lock_configuration.html.markdown @@ -10,9 +10,9 @@ description: |- Provides an S3 bucket Object Lock configuration resource. For more information about Object Locking, go to [Using S3 Object Lock](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock.html) in the Amazon S3 User Guide. -~> **NOTE:** This resource **does not enable** Object Lock for _new_ buckets. It configures a default retention period for objects placed in the specified bucket. -Thus, to **enable** Object Lock for a _new_ bucket, see the the [`aws_s3_bucket` resource](s3_bucket.html.markdown) or the [following example](#Example-Usage). -If you want to turn on Object Lock for an _existing_ bucket, contact AWS Support. +~> **NOTE:** This resource **does not enable** Object Lock for **new** buckets. It configures a default retention period for objects placed in the specified bucket. +Thus, to **enable** Object Lock for a **new** bucket, see the [Using object lock configuration](s3_bucket.html.markdown#Using-object-lock-configuration) section in the `aws_s3_bucket` resource or the [Object Lock configuration for a new bucket](#object-lock-configuration-for-a-new-bucket) example below. +If you want to **enable** Object Lock for an **existing** bucket, contact AWS Support and see the [Object Lock configuration for an existing bucket](#object-lock-configuration-for-an-existing-bucket) example below. ## Example Usage @@ -39,6 +39,44 @@ resource "aws_s3_bucket_object_lock_configuration" "example" { } ``` +### Object Lock configuration for an existing bucket + +This is a multistep process that requires AWS Support intervention. + +1. Enable versioning on your S3 bucket, if you have not already done so. +Doing so will generate an "Object Lock token" in the back-end. + + ```terraform + resource "aws_s3_bucket" "example" { + bucket = "mybucket" + } + + resource "aws_s3_bucket_versioning" "example" { + bucket = aws_s3_bucket.example.bucket + + versioning_configuration { + status = "Enabled" + } + } + ``` + +2. Contact AWS Support to provide you with the "Object Lock token" for the specified bucket and use the token within your new `aws_s3_bucket_object_lock_configuration` resource. + + ```terraform + resource "aws_s3_bucket_object_lock_configuration" "example" { + bucket = aws_s3_bucket.example.bucket + + rule { + default_retention { + mode = "COMPLIANCE" + days = 5 + } + } + + token = "exampletoken1234" + } + ``` + ## Argument Reference The following arguments are supported: @@ -47,7 +85,8 @@ The following arguments are supported: * `expected_bucket_owner` - (Optional, Forces new resource) The account ID of the expected bucket owner. * `object_lock_enabled` - (Optional, Forces new resource) Indicates whether this bucket has an Object Lock configuration enabled. Defaults to `Enabled`. Valid values: `Enabled`. * `rule` - (Required) Configuration block for specifying the Object Lock rule for the specified object [detailed below](#rule). -* `token` - (Optional) A token to allow Object Lock to be enabled for an existing bucket. +* `token` - (Optional) A token to allow Object Lock to be enabled for an existing bucket. You must contact AWS support for the bucket's "Object Lock token". +The token is generated in the back-end when [versioning](https://docs.aws.amazon.com/AmazonS3/latest/userguide/manage-versioning-examples.html) is enabled on a bucket. For more details on versioning, see the [`aws_s3_bucket_versioning` resource](s3_bucket_versioning.html.markdown). ### rule