diff --git a/base-label/README.md b/base-label/README.md new file mode 100644 index 0000000..40d3e99 --- /dev/null +++ b/base-label/README.md @@ -0,0 +1,41 @@ +## Requirements + +| Name | Version | +|------|---------| +| [terraform](#requirement\_terraform) | >= 1.0.0 | + +## Providers + +| Name | Version | +|------|---------| +| [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 | +|------|-------------|------|---------|:--------:| +| [application](#input\_application) | Application label | `string` | `null` | no | +| [business](#input\_business) | Business label (organization, program, etc) | `string` | `null` | no | +| [custom](#input\_custom) | Custom label | `string` | `null` | no | +| [environment](#input\_environment) | Environment label | `string` | `null` | no | +| [filename](#input\_filename) | Filename of YAML file with tags (see documentation for structure) | `string` | `null` | no | +| [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 | +|------|-------------| +| [core](#output\_core) | Map of base label format values | +| [formats](#output\_formats) | Map of base label format convenience outputs | +| [prefixes](#output\_prefixes) | Pre-defined prefixes map. If missing, there is no prefix for the component. | +| [version](#output\_version) | Module version information. Cannot be passed back in tags because it will overwrite other module tags | diff --git a/tags/README.md b/tags/README.md new file mode 100644 index 0000000..1f408f1 --- /dev/null +++ b/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 | +|------|---------| +| [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 | +|------|-------------|------|---------|:--------:| +| [filename](#input\_filename) | Filename of YAML file with tags (see documentation for structure) | `string` | `null` | no | +| [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 | +| [finops](#input\_finops) | FinOps Related tags (required: number, name; not-required: role) | 
object({
    number = number
    name   = string
    role   = optional(string)
  })
| 
{
  "name": null,
  "number": null
}
| no | +| [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 | +|------|-------------| +| [finops\_roles](#output\_finops\_roles) | Map of finops\_project\_role values based on finops\_project\_name and finops.roles in YAML | +| [finops\_tags](#output\_finops\_tags) | Map of finops tags by short name for individual selection | +| [map](#output\_map) | Standard AWS Migration Acceleration Program (MAP) tag | +| [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. | +| [tag\_hierarchy](#output\_tag\_hierarchy) | Map of processed tag key/value pairs grouped by category | +| [tags](#output\_tags) | Map of processed tag key/value pairs | +| [version](#output\_version) | Module version information. Cannot be passed back in tags because it will overwrite other module tags |