cloudposse · johncblandii · Jul 29, 2020 · Jul 28, 2020 · Jul 28, 2020 · Jul 28, 2020
diff --git a/Makefile b/Makefile
@@ -8,4 +8,11 @@ export README_DEPS ?= docs/targets.md docs/terraform.md
 
 ## Lint terraform code
 lint:
-	$(SELF) terraform/install terraform/get-modules terraform/get-plugins terraform/lint terraform/validate
+	$(SELF) terraform/install terraform/get-modules terraform/get-plugins terraform/lint terraform/validate
+
+## Run Terraform commands in the examples/complete folder; e.g. make test/plan
+test/%:
+	@cd examples/complete && \
+	terraform init && \
+	terraform $* -var-file=fixtures.us-west-1.tfvars && \
+	terraform $* -var-file=grants.us-west-1.tfvars
diff --git a/README.md b/README.md
diff --git a/README.yaml b/README.yaml
@@ -78,16 +78,50 @@ description: |-
 
 # How to use this project
 usage: |-
+  Using a [canned ACL](https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html).
+
+  ```hcl
+  module "s3_bucket" {
+    source                   = "git::https://github.com/cloudposse/terraform-aws-s3-bucket.git?ref=master"
+    acl                      = "private"
+    enabled                  = true
+    user_enabled             = true
+    versioning_enabled       = false
+    allowed_bucket_actions   = ["s3:GetObject", "s3:ListBucket", "s3:GetBucketLocation"]
+    name                     = "app"
+    stage                    = "test"
+    namespace                = "eg"
+  }
+  ```
+
+  Using [grants](https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html) to enable access to another account and for logging.
+
   ```hcl
   module "s3_bucket" {
     source                   = "git::https://github.com/cloudposse/terraform-aws-s3-bucket.git?ref=master"
+    acl                      = ""
     enabled                  = true
     user_enabled             = true
     versioning_enabled       = false
     allowed_bucket_actions   = ["s3:GetObject", "s3:ListBucket", "s3:GetBucketLocation"]
     name                     = "app"
     stage                    = "test"
     namespace                = "eg"
+
+    grants = [
+      {
+        id          = "012abc345def678ghi901" # Canonical user or account id
+        type        = "CanonicalUser"
+        permissions = ["FULL_CONTROL"]
+        uri         = null
+      },
+      {
+        id          = null
+        type        = "Group"
+        permissions = ["READ", "WRITE"]
+        uri         = "http://acs.amazonaws.com/groups/s3/LogDelivery"
+      },
+    ]
   }
   ```
 

diff --git a/docs/targets.md b/docs/targets.md
@@ -1,10 +1,13 @@
+<!-- markdownlint-disable -->
 ## Makefile Targets
-```
+```text
 Available targets:
 
   help                                Help screen
   help/all                            Display help for all targets
   help/short                          This help short screen
   lint                                Lint terraform code
+  test/%                              Run Terraform commands in the examples/complete folder; e.g. make test/plan
 
 ```
+<!-- markdownlint-restore -->
diff --git a/docs/terraform.md b/docs/terraform.md
@@ -1,55 +1,71 @@
+## Requirements
+
+| Name | Version |
+|------|---------|
+| terraform | ~> 0.12.0 |
+| aws | ~> 2.0 |
+| local | ~> 1.2 |
+| null | ~> 2.0 |
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| aws | ~> 2.0 |
+
 ## Inputs
 
 | Name | Description | Type | Default | Required |
-|------|-------------|:----:|:-----:|:-----:|
-| abort_incomplete_multipart_upload_days | Maximum time (in days) that you want to allow multipart uploads to remain in progress | number | `5` | no |
-| acl | The canned ACL to apply. We recommend `private` to avoid exposing sensitive information | string | `private` | no |
-| allow_encrypted_uploads_only | Set to `true` to prevent uploads of unencrypted objects to S3 bucket | bool | `false` | no |
-| allowed_bucket_actions | List of actions the user is permitted to perform on the S3 bucket | list(string) | `<list>` | no |
-| attributes | Additional attributes (e.g. `1`) | list(string) | `<list>` | no |
-| block_public_acls | Set to `false` to disable the blocking of new public access lists on the bucket | bool | `true` | no |
-| block_public_policy | Set to `false` to disable the blocking of new public policies on the bucket | bool | `true` | no |
-| cors_rule_inputs | Specifies the allowed headers, methods, origins and exposed headers when using CORS on this bucket | object | `null` | no |
-| delimiter | Delimiter to be used between `namespace`, `environment`, `stage`, `name` and `attributes` | string | `-` | no |
-| enable_glacier_transition | Enables the transition to AWS Glacier which can cause unnecessary costs for huge amount of small files | bool | `true` | no |
-| enable_standard_ia_transition | Enables the transition to STANDARD_IA | bool | `false` | no |
-| enabled | Set to false to prevent the module from creating any resources | bool | `true` | no |
-| environment | Environment, e.g. 'prod', 'staging', 'dev', 'pre-prod', 'UAT' | string | `` | no |
-| expiration_days | Number of days after which to expunge the objects | number | `90` | no |
-| force_destroy | A boolean string that indicates all objects should be deleted from the bucket so that the bucket can be destroyed without error. These objects are not recoverable | bool | `false` | no |
-| glacier_transition_days | Number of days after which to move the data to the glacier storage tier | number | `60` | no |
-| ignore_public_acls | Set to `false` to disable the ignoring of public access lists on the bucket | bool | `true` | no |
-| kms_master_key_arn | The AWS KMS master key ARN used for the `SSE-KMS` encryption. This can only be used when you set the value of `sse_algorithm` as `aws:kms`. The default aws/s3 AWS KMS master key is used if this element is absent while the `sse_algorithm` is `aws:kms` | string | `` | no |
-| lifecycle_rule_enabled | Enable or disable lifecycle rule | bool | `false` | no |
-| lifecycle_tags | Tags filter. Used to manage object lifecycle events | map(string) | `<map>` | no |
-| name | Solution name, e.g. 'app' or 'jenkins' | string | `` | no |
-| namespace | Namespace, which could be your organization name or abbreviation, e.g. 'eg' or 'cp' | string | `` | no |
-| noncurrent_version_expiration_days | Specifies when noncurrent object versions expire | number | `90` | no |
-| noncurrent_version_transition_days | Number of days to persist in the standard storage tier before moving to the glacier tier infrequent access tier | number | `30` | no |
-| policy | A valid bucket policy JSON document. Note that if the policy document is not specific enough (but still valid), Terraform may view the policy as constantly changing in a terraform plan. In this case, please make sure you use the verbose/specific version of the policy | string | `` | no |
-| prefix | Prefix identifying one or more objects to which the rule applies | string | `` | no |
-| region | If specified, the AWS region this bucket should reside in. Otherwise, the region used by the callee | string | `` | no |
-| restrict_public_buckets | Set to `false` to disable the restricting of making the bucket public | bool | `true` | no |
-| sse_algorithm | The server-side encryption algorithm to use. Valid values are `AES256` and `aws:kms` | string | `AES256` | no |
-| stage | Stage, e.g. 'prod', 'staging', 'dev', OR 'source', 'build', 'test', 'deploy', 'release' | string | `` | no |
-| standard_transition_days | Number of days to persist in the standard storage tier before moving to the infrequent access tier | number | `30` | no |
-| tags | Additional tags (e.g. `map('BusinessUnit','XYZ')` | map(string) | `<map>` | no |
-| user_enabled | Set to `true` to create an IAM user with permission to access the bucket | bool | `false` | no |
-| versioning_enabled | A state of versioning. Versioning is a means of keeping multiple variants of an object in the same bucket | bool | `false` | no |
+|------|-------------|------|---------|:--------:|
+| abort\_incomplete\_multipart\_upload\_days | Maximum time (in days) that you want to allow multipart uploads to remain in progress | `number` | `5` | no |
+| acl | The [canned ACL](https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl) to apply. We recommend `private` to avoid exposing sensitive information. Conflicts with `grants`. | `string` | `"private"` | no |
+| allow\_encrypted\_uploads\_only | Set to `true` to prevent uploads of unencrypted objects to S3 bucket | `bool` | `false` | no |
+| allowed\_bucket\_actions | List of actions the user is permitted to perform on the S3 bucket | `list(string)` | <pre>[<br>  "s3:PutObject",<br>  "s3:PutObjectAcl",<br>  "s3:GetObject",<br>  "s3:DeleteObject",<br>  "s3:ListBucket",<br>  "s3:ListBucketMultipartUploads",<br>  "s3:GetBucketLocation",<br>  "s3:AbortMultipartUpload"<br>]</pre> | no |
+| attributes | Additional attributes (e.g. `1`) | `list(string)` | `[]` | no |
+| block\_public\_acls | Set to `false` to disable the blocking of new public access lists on the bucket | `bool` | `true` | no |
+| block\_public\_policy | Set to `false` to disable the blocking of new public policies on the bucket | `bool` | `true` | no |
+| cors\_rule\_inputs | Specifies the allowed headers, methods, origins and exposed headers when using CORS on this bucket | <pre>list(object({<br>    allowed_headers = list(string)<br>    allowed_methods = list(string)<br>    allowed_origins = list(string)<br>    expose_headers  = list(string)<br>    max_age_seconds = number<br>  }))</pre> | `null` | no |
+| delimiter | Delimiter to be used between `namespace`, `environment`, `stage`, `name` and `attributes` | `string` | `"-"` | no |
+| enable\_glacier\_transition | Enables the transition to AWS Glacier which can cause unnecessary costs for huge amount of small files | `bool` | `true` | no |
+| enable\_standard\_ia\_transition | Enables the transition to STANDARD\_IA | `bool` | `false` | no |
+| enabled | Set to false to prevent the module from creating any resources | `bool` | `true` | no |
+| environment | Environment, e.g. 'prod', 'staging', 'dev', 'pre-prod', 'UAT' | `string` | `""` | no |
+| expiration\_days | Number of days after which to expunge the objects | `number` | `90` | no |
+| force\_destroy | A boolean string that indicates all objects should be deleted from the bucket so that the bucket can be destroyed without error. These objects are not recoverable | `bool` | `false` | no |
+| glacier\_transition\_days | Number of days after which to move the data to the glacier storage tier | `number` | `60` | no |
+| grants | An ACL policy grant. Conflicts with `acl`. Set `acl` to `null` to use this. | <pre>list(object({<br>    id          = string<br>    type        = string<br>    permissions = list(string)<br>    uri         = string<br>  }))</pre> | `null` | no |
+| ignore\_public\_acls | Set to `false` to disable the ignoring of public access lists on the bucket | `bool` | `true` | no |
+| kms\_master\_key\_arn | The AWS KMS master key ARN used for the `SSE-KMS` encryption. This can only be used when you set the value of `sse_algorithm` as `aws:kms`. The default aws/s3 AWS KMS master key is used if this element is absent while the `sse_algorithm` is `aws:kms` | `string` | `""` | no |
+| lifecycle\_rule\_enabled | Enable or disable lifecycle rule | `bool` | `false` | no |
+| lifecycle\_tags | Tags filter. Used to manage object lifecycle events | `map(string)` | `{}` | no |
+| name | Solution name, e.g. 'app' or 'jenkins' | `string` | `""` | no |
+| namespace | Namespace, which could be your organization name or abbreviation, e.g. 'eg' or 'cp' | `string` | `""` | no |
+| noncurrent\_version\_expiration\_days | Specifies when noncurrent object versions expire | `number` | `90` | no |
+| noncurrent\_version\_transition\_days | Number of days to persist in the standard storage tier before moving to the glacier tier infrequent access tier | `number` | `30` | no |
+| policy | A valid bucket policy JSON document. Note that if the policy document is not specific enough (but still valid), Terraform may view the policy as constantly changing in a terraform plan. In this case, please make sure you use the verbose/specific version of the policy | `string` | `""` | no |
+| prefix | Prefix identifying one or more objects to which the rule applies | `string` | `""` | no |
+| region | If specified, the AWS region this bucket should reside in. Otherwise, the region used by the callee | `string` | `""` | no |
+| restrict\_public\_buckets | Set to `false` to disable the restricting of making the bucket public | `bool` | `true` | no |
+| sse\_algorithm | The server-side encryption algorithm to use. Valid values are `AES256` and `aws:kms` | `string` | `"AES256"` | no |
+| stage | Stage, e.g. 'prod', 'staging', 'dev', OR 'source', 'build', 'test', 'deploy', 'release' | `string` | `""` | no |
+| standard\_transition\_days | Number of days to persist in the standard storage tier before moving to the infrequent access tier | `number` | `30` | no |
+| tags | Additional tags (e.g. `map('BusinessUnit','XYZ')` | `map(string)` | `{}` | no |
+| user\_enabled | Set to `true` to create an IAM user with permission to access the bucket | `bool` | `false` | no |
+| versioning\_enabled | A state of versioning. Versioning is a means of keeping multiple variants of an object in the same bucket | `bool` | `false` | no |
 
 ## Outputs
 
 | Name | Description |
 |------|-------------|
-| access_key_id | The access key ID |
-| bucket_arn | Bucket ARN |
-| bucket_domain_name | FQDN of bucket |
-| bucket_id | Bucket Name (aka ID) |
-| bucket_regional_domain_name | The bucket region-specific domain name |
+| access\_key\_id | The access key ID |
+| bucket\_arn | Bucket ARN |
+| bucket\_domain\_name | FQDN of bucket |
+| bucket\_id | Bucket Name (aka ID) |
+| bucket\_regional\_domain\_name | The bucket region-specific domain name |
 | enabled | Is module enabled |
-| secret_access_key | The secret access key. This will be written to the state file in plain-text |
-| user_arn | The ARN assigned by AWS for the user |
-| user_enabled | Is user creation enabled |
-| user_name | Normalized IAM user name |
-| user_unique_id | The user unique ID assigned by AWS |
+| secret\_access\_key | The secret access key. This will be written to the state file in plain-text |
+| user\_arn | The ARN assigned by AWS for the user |
+| user\_enabled | Is user creation enabled |
+| user\_name | Normalized IAM user name |
+| user\_unique\_id | The user unique ID assigned by AWS |
 
diff --git a/examples/complete/grants.us-west-1.tfvars b/examples/complete/grants.us-west-1.tfvars
@@ -0,0 +1,26 @@
+region = "us-west-1"
+
+namespace = "eg"
+
+stage = "test"
+
+name = "s3-grants-test"
+
+acl = ""
+
+grants = [
+  {
+    id          = null
+    type        = "Group"
+    permissions = ["READ", "WRITE"]
+    uri         = "http://acs.amazonaws.com/groups/s3/LogDelivery"
+  },
+]
+
+force_destroy = true
+
+versioning_enabled = false
+
+allow_encrypted_uploads_only = true
+
+allowed_bucket_actions = ["s3:PutObject", "s3:PutObjectAcl", "s3:GetObject", "s3:DeleteObject", "s3:ListBucket", "s3:ListBucketMultipartUploads", "s3:GetBucketLocation", "s3:AbortMultipartUpload"]
diff --git a/examples/complete/main.tf b/examples/complete/main.tf
@@ -11,8 +11,10 @@ module "s3_bucket" {
   namespace                    = var.namespace
   stage                        = var.stage
   name                         = var.name
+  attributes                   = var.attributes
   acl                          = var.acl
   force_destroy                = var.force_destroy
+  grants                       = var.grants
   versioning_enabled           = var.versioning_enabled
   allow_encrypted_uploads_only = var.allow_encrypted_uploads_only
   allowed_bucket_actions       = var.allowed_bucket_actions