updates to examples/docs per pr feedback

Author: cdaniluk

README.md

@@ -29,6 +29,10 @@ To use this bucket to manage the state for other AWS accounts, you must create I
 
 See [Use AssumeRole to Provision AWS Resources Across Accounts](https://learn.hashicorp.com/tutorials/terraform/aws-assumerole) for more information on this pattern.
 
+This module is not intended to hold the state for the account in which it is created. If the account itself is also Terraform managed, it is recommended to create a separate bucket for its own state manually or via a different IaC method (e.g., CloudFormation). 
+
+This module will create a CloudFormation stack and an optional wrapper script to deploy it. This stack is suitable to run in any account that will store its Terraform state in this backend. It creates an IAM role with the AdministratorAccess policy attached and with an External ID.
+
 <!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
 ## Requirements
 
@@ -95,6 +99,7 @@ No modules.
 
 | Name | Description |
 |------|-------------|
+| <a name="output_external_id"></a> [external\_id](#output\_external\_id) | External ID attached to IAM role in managed accounts |
 | <a name="output_kms_key_arn"></a> [kms\_key\_arn](#output\_kms\_key\_arn) | ARN of KMS Key for S3 bucket |
-| <a name="output_s3_bucket_backend"></a> [s3\_bucket\_backend](#output\_s3\_bucket\_backend) | S3 bucket |
+| <a name="output_s3_bucket_backend"></a> [s3\_bucket\_backend](#output\_s3\_bucket\_backend) | S3 bucket used to store TF state |
 <!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->

examples/basic/README.md

@@ -1,5 +1,17 @@
-# Basic Backend Example
-Creates resources for a secure backend in AWS
+#  Basic Backend Example
+Creates resources for a secure backend in AWS to support separate AWS accounts. To use this backend, use the following provider definition:
+
+```
+provider "aws" {
+  region = var.region
+
+  assume_role {
+    role_arn    = "arn:aws-us-gov:iam::012345678901:role/Terraform"
+    external_id = "YourExternalID"
+  }
+}
+
+You will need to run Terraform with IAM credentials of the account that holds the state rather than the accounts that you are working on.
 
 <!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
 ## Requirements
@@ -8,23 +20,17 @@ No requirements.
 
 ## Providers
 
-| Name | Version |
-|------|---------|
-| <a name="provider_aws"></a> [aws](#provider\_aws) | n/a |
+No providers.
 
 ## Modules
 
 | Name | Source | Version |
 |------|--------|---------|
-| <a name="module_backend"></a> [backend](#module\_backend) | ../.. |  |
-| <a name="module_tags"></a> [tags](#module\_tags) | rhythmictech/tags/terraform | 1.0.0 |
+| <a name="module_tfstate"></a> [tfstate](#module\_tfstate) | ../.. | n/a |
 
 ## Resources
 
-| Name | Type |
-|------|------|
-| [aws_caller_identity.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) | data source |
-| [aws_region.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/region) | data source |
+No resources.
 
 ## Inputs
 

examples/basic/main.tf

@@ -1,35 +1,7 @@
-data "aws_caller_identity" "current" {}
-data "aws_region" "current" {}
-
-locals {
-  env       = "sandbox"
-  name      = "example"
-  namespace = "aws-rhythmic-sandbox"
-  owner     = "Rhythmictech Engineering"
-
-  extra_tags = {
-    delete_me = "please"
-    purpose   = "testing"
-  }
-}
-
-module "tags" {
-  source  = "rhythmictech/tags/terraform"
-  version = "1.0.0"
-
-  names = [local.name, local.env, local.namespace]
-
-  tags = merge({
-    "Env"       = local.env,
-    "Namespace" = local.namespace,
-    "Owner"     = local.owner
-  }, local.extra_tags)
-}
-
-module "backend" {
+module "tfstate" {
   source = "../.."
 
-  bucket         = "${data.aws_caller_identity.current.account_id}-${data.aws_region.current.name}-${module.tags.name}"
-  kms_alias_name = "${data.aws_caller_identity.current.account_id}-${data.aws_region.current.name}-${module.tags.name}"
-  tags           = module.tags.tags
+  bucket_name                = "tf-state-remote"
+  create_assumerole_template = true
+  dynamo_locktable_name      = "tf-locktable-remote"
 }

examples/external-logging/README.md

@@ -0,0 +1,68 @@
+# Workspaces Backend Example
+Creates resources for a secure backend in AWS to support multiple AWS accounts. To use this backend with accounts managed by Terraform workspaces, use the following provider definition and variable:
+
+```
+provider "aws" {
+  region = var.region
+
+  assume_role {
+    role_arn    = var.workspace_iam_roles[terraform.workspace].role_arn
+    external_id = var.workspace_iam_roles[terraform.workspace].external_id
+  }
+}
+
+variable "workspace_iam_roles" {
+  description = "IAM roles to assume"
+  type        = any
+}
+
+```
+
+Then define variable entries for each account:
+
+```
+workspace_iam_roles = {
+  dev = {
+    role_arn    = "arn:aws-us-gov:iam::012345678901:role/Terraform"
+    external_id = "YourExternalID"
+  }
+  test = {
+    role_arn    = "arn:aws:iam::012345678902:role/Terraform"
+    external_id = "YourExternalID"
+  }
+  prod = {
+    role_arn    = "arn:aws-us-gov:iam::012345678903:role/Terraform"
+    external_id = "YourExternalID"
+  }
+}
+```
+
+You will need to run Terraform with IAM credentials of the account that holds the state rather than the accounts that you are working on.
+
+<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+## Requirements
+
+No requirements.
+
+## Providers
+
+No providers.
+
+## Modules
+
+| Name | Source | Version |
+|------|--------|---------|
+| <a name="module_tfstate"></a> [tfstate](#module\_tfstate) | ../.. | n/a |
+
+## Resources
+
+No resources.
+
+## Inputs
+
+No inputs.
+
+## Outputs
+
+No outputs.
+<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->

examples/external-logging/main.tf

@@ -0,0 +1,7 @@
+module "tfstate" {
+  source = "../.."
+
+  bucket_name                = "tf-state-remote"
+  create_assumerole_template = true
+  dynamo_locktable_name      = "tf-locktable-remote"
+}

examples/workspaces/README.md

@@ -1,9 +1,14 @@
-output "s3_bucket_backend" {
-  description = "S3 bucket"
-  value       = aws_s3_bucket.this.bucket
+output "external_id" {
+  description = "External ID attached to IAM role in managed accounts"
+  value       = local.external_id
 }
 
 output "kms_key_arn" {
   description = "ARN of KMS Key for S3 bucket"
   value       = try(aws_kms_key.this[0].arn, var.kms_key_id)
 }
+
+output "s3_bucket_backend" {
+  description = "S3 bucket used to store TF state"
+  value       = aws_s3_bucket.this.bucket
+}