docs/s3: additional details on object locking for existing buckets

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.

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