add readme

base-label/README.md

@@ -0,0 +1,41 @@
+## Requirements
+
+| Name | Version |
+|------|---------|
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.0.0 |
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| <a name="provider_terraform"></a> [terraform](#provider\_terraform) | n/a |
+
+## Modules
+
+No modules.
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [terraform_data.base_environment](https://registry.terraform.io/providers/hashicorp/terraform/latest/docs/resources/data) | resource |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_application"></a> [application](#input\_application) | Application label | `string` | `null` | no |
+| <a name="input_business"></a> [business](#input\_business) | Business label (organization, program, etc) | `string` | `null` | no |
+| <a name="input_custom"></a> [custom](#input\_custom) | Custom label | `string` | `null` | no |
+| <a name="input_environment"></a> [environment](#input\_environment) | Environment label | `string` | `null` | no |
+| <a name="input_filename"></a> [filename](#input\_filename) | Filename of YAML file with tags (see documentation for structure) | `string` | `null` | no |
+| <a name="input_filenames"></a> [filenames](#input\_filenames) | Filenames of YAML file with tags (see documentation for structure).  Each will be processed and the resultant tags merged | `list(string)` | `[]` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_core"></a> [core](#output\_core) | Map of base label format values |
+| <a name="output_formats"></a> [formats](#output\_formats) | Map of base label format convenience outputs |
+| <a name="output_prefixes"></a> [prefixes](#output\_prefixes) | Pre-defined prefixes map.  If missing, there is no prefix for the component. |
+| <a name="output_version"></a> [version](#output\_version) | Module version information. Cannot be passed back in tags because it will overwrite other module tags |

tags/README.md

@@ -0,0 +1,147 @@
+# About
+
+This submodule allows one to easily set a number of tags, primarily the [finops tags](https://github.e.it.census.gov/terraform/cloud-information/blob/master/aws/documentation/naming-tagging-standard/tags/finops.md).
+Use of this module is **highly** recommended as it reduces errors from the wrong number of zeros in the finops project number, and does some validation
+checking as well.  This takes as input a YAML file, but may also take the values in environment variables.  A YAML file is recommended.
+
+## Features
+* Formatting of FinOps Tags
+  * project number
+  * project name
+  * project role
+* Merging legacy FinOps tags into new tag
+  * Project Number
+  * Project Name
+  * ProjectRole
+  * and many combinations
+* Migration Acceleration Program (MAP) Tagging
+
+These features are in progress.
+
+* CostAllocation
+* Environment
+* infrastructure
+* aws\_organization
+
+## YAML Fields
+### finops
+This section takes four attributes
+* number: an integer corresponding to the assigned FinOps Project Number (>= 0)
+* name: string with the assigned FinOps Project Name (lowercase, underscores)
+* role: a string to append to the finops project name when used with a prefix of +, or to use verbatim. There is no need to
+  repeat the same string in project name, simply use the + preix.
+* roles:  a list of strings for which the module output `finops_roles[key]` will be created.  We use this when we need
+  to define a number of roles and make them selectable in the resource `tags()` attributes.
+
+## Usage
+
+Create a terraform file such as `tags.tf` with the module call.
+
+```hcl
+# tags.tf
+module "tags" {
+  source   = "git@github.e.it.census.gov:terraform-modules/boc-nts//tags"
+  filename = format("%v/%v", path.root, "tags.yml")
+
+  # optional, use to convert old finops and preserve Environemnt and CostAllocation tags
+  legacy_tags = merge(
+    var.account_tags,
+    var.infrastructure_tags,
+    var.application_tags,
+  )
+}
+```
+
+The module uses `tags.yml`, which looks like this:
+
+```yaml
+# tags.yml
+finops:
+  number: 31415
+  name: org_app_env_sample
+  roles:
+    - lambda
+    - log
+    - parameter
+    - role
+    - s3
+    - securitygroup
+```
+
+Then, you'd use a couple of outputs of the module where tags would be present.  Here is an example:
+
+```hcl
+resource "aws_ssm_parameter" "config" {
+  name        = local.ssm_parameter_name
+  description = format("Configuration parameter for %v", "my-parameter"
+  type        = "String"
+  value       = jsonencode({parameter="value"})
+
+  tags = merge(
+    local.base_tags,
+    module.tags.tags,
+    module.tags.finops_roles["parameter"],
+  )
+}
+```
+
+This will create a resoruce withe the following tags (assumes CostAllocation, Organization
+and Environment are set in the `var.*_tags` variables already:
+
+```hcl
+    tags            = {
+        "CostAllocation"        = "directorate:org:app"
+        "Organization"          = "census:directorate:org"
+        "boc:created_by"        = "terraform"
+        "finops_project_name"   = "org_app_env_sample"
+        "finops_project_number" = "fs0000031415"
+        "finops_project_role"   = "org_app_env_sample_parameter"
+    }
+```
+
+## Requirements
+
+No requirements.
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| <a name="provider_terraform"></a> [terraform](#provider\_terraform) | n/a |
+
+## Modules
+
+No modules.
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [terraform_data.aws_organization](https://registry.terraform.io/providers/hashicorp/terraform/latest/docs/resources/data) | resource |
+| [terraform_data.cost_allocation](https://registry.terraform.io/providers/hashicorp/terraform/latest/docs/resources/data) | resource |
+| [terraform_data.environment](https://registry.terraform.io/providers/hashicorp/terraform/latest/docs/resources/data) | resource |
+| [terraform_data.finops](https://registry.terraform.io/providers/hashicorp/terraform/latest/docs/resources/data) | resource |
+| [terraform_data.finops_roles](https://registry.terraform.io/providers/hashicorp/terraform/latest/docs/resources/data) | resource |
+| [terraform_data.infrastructure](https://registry.terraform.io/providers/hashicorp/terraform/latest/docs/resources/data) | resource |
+| [terraform_data.legacy_finops_number](https://registry.terraform.io/providers/hashicorp/terraform/latest/docs/resources/data) | resource |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_filename"></a> [filename](#input\_filename) | Filename of YAML file with tags (see documentation for structure) | `string` | `null` | no |
+| <a name="input_filenames"></a> [filenames](#input\_filenames) | Filenames of YAML file with tags (see documentation for structure).  Each will be processed and the resultant tags merged | `list(string)` | `[]` | no |
+| <a name="input_finops"></a> [finops](#input\_finops) | FinOps Related tags (required: number, name; not-required: role) | <pre>object({<br/>    number = number<br/>    name   = string<br/>    role   = optional(string)<br/>  })</pre> | <pre>{<br/>  "name": null,<br/>  "number": null<br/>}</pre> | no |
+| <a name="input_legacy_tags"></a> [legacy\_tags](#input\_legacy\_tags) | Legacy tags (primarily the older finops tags) for which we will output a conversion | `map(string)` | `{}` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_finops_roles"></a> [finops\_roles](#output\_finops\_roles) | Map of finops\_project\_role values based on finops\_project\_name and finops.roles in YAML |
+| <a name="output_finops_tags"></a> [finops\_tags](#output\_finops\_tags) | Map of finops tags by short name for individual selection |
+| <a name="output_map"></a> [map](#output\_map) | Standard AWS Migration Acceleration Program (MAP) tag |
+| <a name="output_map_tags"></a> [map\_tags](#output\_map\_tags) | Map of AWS Migration Acceleration Program (MAP) tags by usage.  See https://s3.us-west-2.amazonaws.com/map-2.0-customer-documentation/html/AWSMapDocs/Examples.html for more information. |
+| <a name="output_tag_hierarchy"></a> [tag\_hierarchy](#output\_tag\_hierarchy) | Map of processed tag key/value pairs grouped by category |
+| <a name="output_tags"></a> [tags](#output\_tags) | Map of processed tag key/value pairs |
+| <a name="output_version"></a> [version](#output\_version) | Module version information. Cannot be passed back in tags because it will overwrite other module tags |