diff --git a/website/docs/language/settings/backends/s3.mdx b/website/docs/language/settings/backends/s3.mdx index a338a42e1a..3ce1f57f5f 100644 --- a/website/docs/language/settings/backends/s3.mdx +++ b/website/docs/language/settings/backends/s3.mdx @@ -410,12 +410,39 @@ to only a single state object within an S3 bucket is shown below: } ``` -It is not possible to apply such fine-grained access control to the DynamoDB -table used for locking, so it is possible for any user with Terraform access -to lock any workspace state, even if they do not have access to read or write -that state. If a malicious user has such access they could block attempts to -use Terraform against some or all of your workspaces as long as locking is -enabled in the backend configuration. +It is also possible to apply fine-grained access control to the DynamoDB +table used for locking. When Terraform puts the state lock in place during `terraform plan`, it stores the full state file as a document and sets the s3 object key as the partition key for the document. After the state lock is released, Terraform places a digest of the updated state file in DynamoDB. The key is similar to the one for the original state file, but is suffixed with `-md5`. + +The example below shows a simple IAM policy that allows the backend operations role to perform these operations: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect" : "Allow", + "Action" : [ + "dynamodb:DeleteItem", + "dynamodb:GetItem", + "dynamodb:PutItem", + "dynamodb:Query", + "dynamodb:UpdateItem" + ], + "Resource" : ["arn:aws:dynamodb:*:*:table/myorg-state-lock-table"], + "Condition" : { + "ForAllValues:StringEquals" : { + "dynamodb:LeadingKeys" : [ + "myorg-terraform-states/myapp/production/tfstate", // during a state lock the full state file is stored with this key + "myorg-terraform-states/myapp/production/tfstate-md5" // after the lock is released a hash of the statefile's contents are stored with this key + ] + } + } + } + ] +} +``` + +Refer to the [AWS documentation on DynamoDB fine-grained locking](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/specifying-conditions.html) for more details. ### Configuring Custom User-Agent Information