update readme

terraform-modules · Mar 25, 2022 · 795606f · 795606f
1 parent c35d3b9
commit 795606f
Show file tree

Hide file tree

Showing 4 changed files with 74 additions and 39 deletions.
diff --git a/standard/README.md b/standard/README.md
@@ -9,6 +9,12 @@ Other configurations such as versioning or data safegurad tagging (only on the b
 # Usage
 To use the new refactored module with the AWS provider v4.x, use `?ref=3`, otherwise leave this part off.
 
+**Note**: version 2 and version 3 of this module cannot coexist in a directory.  All S3 buckets using this module
+must use the same version.  If you are using the version 2 of the module (without the `?ref=3`), you must
+also include a `versions.tf` which pins the AWS provider at < 4.0.  If using version 3 of the module,
+do not include a `versions.tf`, do not pin the AWS provider.  Two different versions of the provider cannot
+coexist (easily).
+
 ```hcl
 module "my-bucket" {
   source = "git@github.e.it.census.gov:terraform-modules/aws-s3.git//standard?ref=3"
@@ -140,14 +146,17 @@ output "s3_module_settings" {
 
 ## Requirements
 
-No requirements.
+| Name | Version |
+|------|---------|
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 4.0 |
+| <a name="requirement_null"></a> [null](#requirement\_null) | >= 3.1.0 |
 
 ## Providers
 
 | Name | Version |
 |------|---------|
-| <a name="provider_aws"></a> [aws](#provider\_aws) | n/a |
-| <a name="provider_null"></a> [null](#provider\_null) | n/a |
+| <a name="provider_aws"></a> [aws](#provider\_aws) | >= 4.0 |
+| <a name="provider_null"></a> [null](#provider\_null) | >= 3.1.0 |
 | <a name="provider_template"></a> [template](#provider\_template) | n/a |
 
 ## Modules

diff --git a/standard/main.tf b/standard/main.tf
@@ -10,6 +10,12 @@
 * # Usage 
 * To use the new refactored module with the AWS provider v4.x, use `?ref=3`, otherwise leave this part off.
 *
+* **Note**: version 2 and version 3 of this module cannot coexist in a directory.  All S3 buckets using this module
+* must use the same version.  If you are using the version 2 of the module (without the `?ref=3`), you must
+* also include a `versions.tf` which pins the AWS provider at < 4.0.  If using version 3 of the module,
+* do not include a `versions.tf`, do not pin the AWS provider.  Two different versions of the provider cannot
+* coexist (easily).
+*
 * ```hcl
 * module "my-bucket" {
 *   source = "git@github.e.it.census.gov:terraform-modules/aws-s3.git//standard?ref=3"

diff --git a/title26/README.md b/title26/README.md
@@ -9,30 +9,39 @@ FTI (Title26).  This includes
 # Usage
 To use the new refactored module with the AWS provider v4.x, use `?ref=3`, otherwise leave this part off.
 
+**Note**: version 2 and version 3 of this module cannot coexist in a directory.  All S3 buckets using this module
+must use the same version.  If you are using the version 2 of the module (without the `?ref=3`), you must
+also include a `versions.tf` which pins the AWS provider at < 4.0.  If using version 3 of the module,
+do not include a `versions.tf`, do not pin the AWS provider.  Two different versions of the provider cannot
+coexist (easily).
+
+```hcl
+module "my-bucket" {
+
 ```hcl
 module "mybucket" {
   source = "git@github.e.it.census.gov:terraform-modules/aws-s3.git//title26?ref=3"
 
-  bucket_name = "myt26bucket"
-  access_log_bucket = "mylogbucket"
-  # enable_title26 = true
-  kms_admin_roles   = [ aws_iam_role.cloud-admin.arn ]
+  bucket\_name = "myt26bucket"
+  access\_log\_bucket = "mylogbucket"
+  # enable\_title26 = true
+  kms\_admin\_roles   = [ aws\_iam\_role.cloud-admin.arn ]
 
   ## optional
-  # kms_policy_document = data.aws_iam_policy_document.mypolicy.json
-  # bucket_policy_document = data.aws_iam_policy_document.mybucketpolicy.json
-  # bucket_policy_document_template = data.aws_iam_policy_document.my-bucketpolicy-template.json
-  # name_include_account   = true
-  # name_include_region    = true
-  # name_include_region_compact = true
-  # name_enforce_region_compact = false
+  # kms\_policy\_document = data.aws\_iam\_policy\_document.mypolicy.json
+  # bucket\_policy\_document = data.aws\_iam\_policy\_document.mybucketpolicy.json
+  # bucket\_policy\_document\_template = data.aws\_iam\_policy\_document.my-bucketpolicy-template.json
+  # name\_include\_account   = true
+  # name\_include\_region    = true
+  # name\_include\_region\_compact = true
+  # name\_enforce\_region\_compact = false
 }
 ```
 
 Sample policy for write access to the bucket and use of KMS key
 
 ```hcl
-data "aws_iam_policy_document" "policy" {
+data "aws\_iam\_policy\_document" "policy" {
   statement {
     sid = "ListBuckets"
     actions = [
@@ -52,8 +61,8 @@ data "aws_iam_policy_document" "policy" {
       "s3:DeleteObject"
     ]
     resources = [
-      module.mybucket.s3_bucket_arn,
-      format("%v/*", mybucket.s3_bucket_arn),
+      module.mybucket.s3\_bucket\_arn,
+      format("%v/*", mybucket.s3\_bucket\_arn),
     ]
   }
   statement {
@@ -65,18 +74,18 @@ data "aws_iam_policy_document" "policy" {
       "kms:Encrypt",
       "kms:Decrypt"
     ]
-    resources = [module.mybucket.kms_key_id]
+    resources = [module.mybucket.kms\_key\_id]
   }
 }
 
-resource "aws_iam_policy" "policy" {
+resource "aws\_iam\_policy" "policy" {
   name        = "mypolicy-s3-access"
   description = "Policy for S3 access"
-  policy      = data.aws_iam_policy_document.policy.json
+  policy      = data.aws\_iam\_policy\_document.policy.json
 }
 ```
 
-This automatically enables the enable\_title26 flag, giving you a tag of `boc:safeguard=title26`.
+This automatically enables the enable_title26 flag, giving you a tag of `boc:safeguard=title26`.
 It does all you to add other safeguards as necessary (title13, pii, etc), and these are joined together
 to make a comma separated list.
 
@@ -95,56 +104,58 @@ optionally requires explicit encryption (`require_explicit_encryption` flag, def
 and address restrictions (lists `allowed_cidr` and `allowed_endpoints`).
 
 # Options
-## Options :: name\_include\_account
+## Options :: name_include_account
 Use of this flag as true will include AWS account ID after the bucket name (name-ACCOUNTID).  Default
 is false.
 
-## Options :: name\_include\_region
+## Options :: name_include_region
 Use of this flag as true will include current region after the bucket name (name-REGION).  Default
 is false.  If used in conjunction with `name_include_account`, the region will be at the end.
 
-## Options :: name\_include\_region\_compact
+## Options :: name_include_region_compact
 This flag determines if we compact the region to a shorter name, and use it if the name with the full
 region is longer than the maximum of 63 characters.  It takes the first character of the full region
 name and uses that. For example, `us-gov-west-1` becomes `ugw1`.  The default value is true.
 It is still possible to construct a name that is longer than 63 characters and get a failure, even with
 this shorter region value.
 
-## Options :: name\_enforce\_region\_compact
+## Options :: name_enforce_region_compact
 This flag always compacts the region, no mater whehter the name is longer than 63 characters or not.
 
 # Outputs
 One output of note is the `s3_module_settings`. With this, you can get the settings used when calling the
 module, the original bucket name before prefix and suffixes, and other things.  It is a map.
 
 ```hcl
-output "s3_module_settings" {
+output "s3\_module\_settings" {
   description = "S3 module settings and values"
   value = {
-    bucket_name                 = var.bucket_name
-    resulting_bucket_name       = local.bucket_name
-    resulting_bucket_arn        = aws_s3_bucket.this.arn
-    name_include_region         = var.name_include_region
-    name_include_account        = var.name_include_account
-    name_include_region_compact = var.name_include_region_compact
-    name_enforce_region_compact = var.name_enforce_region_compact
-    account_id                  = local.account_id
+    bucket\_name                 = var.bucket\_name
+    resulting\_bucket\_name       = local.bucket\_name
+    resulting\_bucket\_arn        = aws\_s3\_bucket.this.arn
+    name\_include\_region         = var.name\_include\_region
+    name\_include\_account        = var.name\_include\_account
+    name\_include\_region\_compact = var.name\_include\_region\_compact
+    name\_enforce\_region\_compact = var.name\_enforce\_region\_compact
+    account\_id                  = local.account\_id
     region                      = local.region
-    region_short                = local.region_short
+    region\_short                = local.region\_short
   }
 }
-```
 
 ## Requirements
 
-No requirements.
+| Name | Version |
+|------|---------|
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 4.0 |
+| <a name="requirement_null"></a> [null](#requirement\_null) | >= 3.1.0 |
 
 ## Providers
 
 | Name | Version |
 |------|---------|
-| <a name="provider_aws"></a> [aws](#provider\_aws) | n/a |
-| <a name="provider_null"></a> [null](#provider\_null) | n/a |
+| <a name="provider_aws"></a> [aws](#provider\_aws) | >= 4.0 |
+| <a name="provider_null"></a> [null](#provider\_null) | >= 3.1.0 |
 | <a name="provider_template"></a> [template](#provider\_template) | n/a |
 
 ## Modules

diff --git a/title26/main.tf b/title26/main.tf
@@ -9,6 +9,15 @@
 * 
 * # Usage 
 * To use the new refactored module with the AWS provider v4.x, use `?ref=3`, otherwise leave this part off.
+* 
+* **Note**: version 2 and version 3 of this module cannot coexist in a directory.  All S3 buckets using this module
+* must use the same version.  If you are using the version 2 of the module (without the `?ref=3`), you must
+* also include a `versions.tf` which pins the AWS provider at < 4.0.  If using version 3 of the module,
+* do not include a `versions.tf`, do not pin the AWS provider.  Two different versions of the provider cannot
+* coexist (easily).
+*
+* ```hcl
+* module "my-bucket" {
 *
 * ```hcl
 * module "mybucket" {