Add "tenant", "labels_as_tags", and "descriptors"

docs/terraform.md

@@ -21,21 +21,22 @@ No resources.
 
 | Name | Description | Type | Default | Required |
 |------|-------------|------|---------|:--------:|
-| <a name="input_additional_tag_map"></a> [additional\_tag\_map](#input\_additional\_tag\_map) | Additional tags for appending to tags\_as\_list\_of\_maps. Not added to `tags`. | `map(string)` | `{}` | no |
-| <a name="input_attributes"></a> [attributes](#input\_attributes) | Additional attributes (e.g. `1`) | `list(string)` | `[]` | no |
-| <a name="input_context"></a> [context](#input\_context) | Single object for setting entire context at once.<br>See description of individual variables for details.<br>Leave string and numeric variables as `null` to use default value.<br>Individual variable settings (non-null) override settings in context object,<br>except for attributes, tags, and additional\_tag\_map, which are merged. | `any` | <pre>{<br>  "additional_tag_map": {},<br>  "attributes": [],<br>  "delimiter": null,<br>  "enabled": true,<br>  "environment": null,<br>  "id_length_limit": null,<br>  "label_key_case": null,<br>  "label_order": [],<br>  "label_value_case": null,<br>  "name": null,<br>  "namespace": null,<br>  "regex_replace_chars": null,<br>  "stage": null,<br>  "tags": {}<br>}</pre> | no |
-| <a name="input_delimiter"></a> [delimiter](#input\_delimiter) | Delimiter to be used between `namespace`, `environment`, `stage`, `name` and `attributes`.<br>Defaults to `-` (hyphen). Set to `""` to use no delimiter at all. | `string` | `null` | no |
+| <a name="input_additional_tag_map"></a> [additional\_tag\_map](#input\_additional\_tag\_map) | Additional key-value pairs to add to each map in `tags_as_list_of_maps`. Not added to `tags` or `id`.<br>This is for some rare cases where resources want additional configuration of tags<br>and therefore take a list of maps with tag key, value, and additional configuration. | `map(string)` | `{}` | no |
+| <a name="input_attributes"></a> [attributes](#input\_attributes) | Additional attributes (e.g. `1`) to add to `id` | `list(string)` | `[]` | no |
+| <a name="input_context"></a> [context](#input\_context) | Single object for setting entire context at once.<br>See description of individual variables for details.<br>Leave string and numeric variables as `null` to use default value.<br>Individual variable settings (non-null) override settings in context object,<br>except for attributes, tags, and additional\_tag\_map, which are merged. | `any` | <pre>{<br>  "additional_tag_map": {},<br>  "attributes": [],<br>  "delimiter": null,<br>  "enabled": true,<br>  "environment": null,<br>  "id_length_limit": null,<br>  "label_key_case": null,<br>  "label_order": [],<br>  "label_value_case": null,<br>  "name": null,<br>  "namespace": null,<br>  "regex_replace_chars": null,<br>  "stage": null,<br>  "tags": {},<br>  "tenant": null<br>}</pre> | no |
+| <a name="input_delimiter"></a> [delimiter](#input\_delimiter) | Delimiter to be used between `namespace`, `tenant`, `environment`, `stage`, `name` and `attributes`.<br>Defaults to `-` (hyphen). Set to `""` to use no delimiter at all. | `string` | `null` | no |
 | <a name="input_enabled"></a> [enabled](#input\_enabled) | Set to false to prevent the module from creating any resources | `bool` | `null` | no |
 | <a name="input_environment"></a> [environment](#input\_environment) | Environment, e.g. 'uw2', 'us-west-2', OR 'prod', 'staging', 'dev', 'UAT' | `string` | `null` | no |
 | <a name="input_id_length_limit"></a> [id\_length\_limit](#input\_id\_length\_limit) | Limit `id` to this many characters (minimum 6).<br>Set to `0` for unlimited length.<br>Set to `null` for default, which is `0`.<br>Does not affect `id_full`. | `number` | `null` | no |
 | <a name="input_label_key_case"></a> [label\_key\_case](#input\_label\_key\_case) | The letter case of label keys (`tag` names) (i.e. `name`, `namespace`, `environment`, `stage`, `attributes`) to use in `tags`.<br>Possible values: `lower`, `title`, `upper`.<br>Default value: `title`. | `string` | `null` | no |
-| <a name="input_label_order"></a> [label\_order](#input\_label\_order) | The naming order of the id output and Name tag.<br>Defaults to ["namespace", "environment", "stage", "name", "attributes"].<br>You can omit any of the 5 elements, but at least one must be present. | `list(string)` | `null` | no |
-| <a name="input_label_value_case"></a> [label\_value\_case](#input\_label\_value\_case) | The letter case of output label values (also used in `tags` and `id`).<br>Possible values: `lower`, `title`, `upper` and `none` (no transformation).<br>Default value: `lower`. | `string` | `null` | no |
+| <a name="input_label_order"></a> [label\_order](#input\_label\_order) | The naming order of the id output and Name tag.<br>Defaults to ["namespace", "tenant", "environment", "stage", "name", "attributes"].<br>You can omit any of the 5 elements, but at least one must be present. | `list(string)` | `null` | no |
+| <a name="input_label_value_case"></a> [label\_value\_case](#input\_label\_value\_case) | The letter case of output label values (also used in `tags` and `id`).<br>Possible values: `lower`, `title`, `upper` and `none` (no transformation).<br>Set this to `title` and set `delimiter` to `""` to yield Pascal Case.<br>Default value: `lower`. | `string` | `null` | no |
 | <a name="input_name"></a> [name](#input\_name) | Solution name, e.g. 'app' or 'jenkins' | `string` | `null` | no |
 | <a name="input_namespace"></a> [namespace](#input\_namespace) | Namespace, which could be your organization name or abbreviation, e.g. 'eg' or 'cp' | `string` | `null` | no |
 | <a name="input_regex_replace_chars"></a> [regex\_replace\_chars](#input\_regex\_replace\_chars) | Regex to replace chars with empty string in `namespace`, `environment`, `stage` and `name`.<br>If not set, `"/[^a-zA-Z0-9-]/"` is used to remove all characters other than hyphens, letters and digits. | `string` | `null` | no |
 | <a name="input_stage"></a> [stage](#input\_stage) | Stage, e.g. 'prod', 'staging', 'dev', OR 'source', 'build', 'test', 'deploy', 'release' | `string` | `null` | no |
-| <a name="input_tags"></a> [tags](#input\_tags) | Additional tags (e.g. `map('BusinessUnit','XYZ')` | `map(string)` | `{}` | no |
+| <a name="input_tags"></a> [tags](#input\_tags) | Additional tags (e.g. `{'BusinessUnit': 'XYZ'}`) | `map(string)` | `{}` | no |
+| <a name="input_tenant"></a> [tenant](#input\_tenant) | Usually omitted, but available for distinguishing resources dedicated to a specific customer | `string` | `null` | no |
 
 ## Outputs
 
@@ -44,11 +45,11 @@ No resources.
 | <a name="output_additional_tag_map"></a> [additional\_tag\_map](#output\_additional\_tag\_map) | The merged additional\_tag\_map |
 | <a name="output_attributes"></a> [attributes](#output\_attributes) | List of attributes |
 | <a name="output_context"></a> [context](#output\_context) | Merged but otherwise unmodified input to this module, to be used as context input to other modules.<br>Note: this version will have null values as defaults, not the values actually used as defaults. |
-| <a name="output_delimiter"></a> [delimiter](#output\_delimiter) | Delimiter between `namespace`, `environment`, `stage`, `name` and `attributes` |
+| <a name="output_delimiter"></a> [delimiter](#output\_delimiter) | Delimiter between `namespace`, `tenant`, `environment`, `stage`, `name` and `attributes` |
 | <a name="output_enabled"></a> [enabled](#output\_enabled) | True if module is enabled, false otherwise |
 | <a name="output_environment"></a> [environment](#output\_environment) | Normalized environment |
-| <a name="output_id"></a> [id](#output\_id) | Disambiguated ID restricted to `id_length_limit` characters in total |
-| <a name="output_id_full"></a> [id\_full](#output\_id\_full) | Disambiguated ID not restricted in length |
+| <a name="output_id"></a> [id](#output\_id) | Disambiguated ID string restricted to `id_length_limit` characters in total |
+| <a name="output_id_full"></a> [id\_full](#output\_id\_full) | ID string not restricted in length |
 | <a name="output_id_length_limit"></a> [id\_length\_limit](#output\_id\_length\_limit) | The id\_length\_limit actually used to create the ID, with `0` meaning unlimited |
 | <a name="output_label_order"></a> [label\_order](#output\_label\_order) | The naming order actually used to create the ID |
 | <a name="output_name"></a> [name](#output\_name) | Normalized name |
@@ -57,5 +58,6 @@ No resources.
 | <a name="output_regex_replace_chars"></a> [regex\_replace\_chars](#output\_regex\_replace\_chars) | The regex\_replace\_chars actually used to create the ID |
 | <a name="output_stage"></a> [stage](#output\_stage) | Normalized stage |
 | <a name="output_tags"></a> [tags](#output\_tags) | Normalized Tag map |
-| <a name="output_tags_as_list_of_maps"></a> [tags\_as\_list\_of\_maps](#output\_tags\_as\_list\_of\_maps) | Additional tags as a list of maps, which can be used in several AWS resources |
+| <a name="output_tags_as_list_of_maps"></a> [tags\_as\_list\_of\_maps](#output\_tags\_as\_list\_of\_maps) | This is a list with one map for each `tag`. Each map contains the tag `key`,<br>`value`, and contents of `var.additional_tag_map`. Used in the rare cases<br>where resources need additional configuration information for each tag. |
+| <a name="output_tenant"></a> [tenant](#output\_tenant) | Normalized tenant |
 <!-- markdownlint-restore -->

examples/complete/context.tf

@@ -1,8 +1,3 @@
-# DO NOT COPY THIS FILE
-#
-# This is a specially modified version of this file, since it is used to test
-# the unpublished version of this module. Normally you should use a
-# copy of the file as explained below.
 #
 # ONLY EDIT THIS FILE IN github.com/cloudposse/terraform-null-label
 # All other instances of this file should be a copy of that one
@@ -13,6 +8,8 @@
 # Cloud Posse's standard configuration inputs suitable for passing
 # to Cloud Posse modules.
 #
+# curl -sL https://raw.githubusercontent.com/cloudposse/terraform-null-label/master/exports/context.tf -o context.tf
+#
 # Modules should access the whole context as `module.this.context`
 # to get the input variables with nulls for defaults,
 # for example `context = module.this.context`,
@@ -28,6 +25,7 @@ module "this" {
 
   enabled             = var.enabled
   namespace           = var.namespace
+  tenant              = var.tenant
   environment         = var.environment
   stage               = var.stage
   name                = var.name
@@ -47,25 +45,11 @@ module "this" {
 # Copy contents of cloudposse/terraform-null-label/variables.tf here
 
 variable "context" {
-  type = object({
-    enabled             = bool
-    namespace           = string
-    environment         = string
-    stage               = string
-    name                = string
-    delimiter           = string
-    attributes          = list(string)
-    tags                = map(string)
-    additional_tag_map  = map(string)
-    regex_replace_chars = string
-    label_order         = list(string)
-    id_length_limit     = number
-    label_key_case      = string
-    label_value_case    = string
-  })
+  type = any
   default = {
     enabled             = true
     namespace           = null
+    tenant              = null
     environment         = null
     stage               = null
     name                = null
@@ -88,12 +72,12 @@ variable "context" {
   EOT
 
   validation {
-    condition     = var.context["label_key_case"] == null ? true : contains(["lower", "title", "upper"], var.context["label_key_case"])
+    condition     = lookup(var.context, "label_key_case", null) == null ? true : contains(["lower", "title", "upper"], var.context["label_key_case"])
     error_message = "Allowed values: `lower`, `title`, `upper`."
   }
 
   validation {
-    condition     = var.context["label_value_case"] == null ? true : contains(["lower", "title", "upper", "none"], var.context["label_value_case"])
+    condition     = lookup(var.context, "label_value_case", null) == null ? true : contains(["lower", "title", "upper", "none"], var.context["label_value_case"])
     error_message = "Allowed values: `lower`, `title`, `upper`, `none`."
   }
 }
@@ -110,6 +94,12 @@ variable "namespace" {
   description = "Namespace, which could be your organization name or abbreviation, e.g. 'eg' or 'cp'"
 }
 
+variable "tenant" {
+  type        = string
+  default     = null
+  description = "Usually omitted, but available for distinguishing resources dedicated to a specific customer"
+}
+
 variable "environment" {
   type        = string
   default     = null
@@ -132,35 +122,39 @@ variable "delimiter" {
   type        = string
   default     = null
   description = <<-EOT
-    Delimiter to be used between `namespace`, `environment`, `stage`, `name` and `attributes`.
+    Delimiter to be used between `namespace`, `tenant`, `environment`, `stage`, `name` and `attributes`.
     Defaults to `-` (hyphen). Set to `""` to use no delimiter at all.
   EOT
 }
 
 variable "attributes" {
   type        = list(string)
   default     = []
-  description = "Additional attributes (e.g. `1`)"
+  description = "Additional attributes (e.g. `1`) to add to `id`"
 }
 
 variable "tags" {
   type        = map(string)
   default     = {}
-  description = "Additional tags (e.g. `map('BusinessUnit','XYZ')`"
+  description = "Additional tags (e.g. `{'BusinessUnit': 'XYZ'}`)"
 }
 
 variable "additional_tag_map" {
   type        = map(string)
   default     = {}
-  description = "Additional tags for appending to tags_as_list_of_maps. Not added to `tags`."
+  description = <<-EOT
+    Additional key-value pairs to add to each map in `tags_as_list_of_maps`. Not added to `tags` or `id`.
+    This is for some rare cases where resources want additional configuration of tags
+    and therefore take a list of maps with tag key, value, and additional configuration.
+    EOT
 }
 
 variable "label_order" {
   type        = list(string)
   default     = null
   description = <<-EOT
     The naming order of the id output and Name tag.
-    Defaults to ["namespace", "environment", "stage", "name", "attributes"].
+    Defaults to ["namespace", "tenant", "environment", "stage", "name", "attributes"].
     You can omit any of the 5 elements, but at least one must be present.
   EOT
 }
@@ -178,11 +172,15 @@ variable "id_length_limit" {
   type        = number
   default     = null
   description = <<-EOT
-    Limit `id` to this many characters.
+    Limit `id` to this many characters (minimum 6).
     Set to `0` for unlimited length.
     Set to `null` for default, which is `0`.
     Does not affect `id_full`.
   EOT
+  validation {
+    condition     = var.id_length_limit == null ? true : var.id_length_limit >= 6 || var.id_length_limit == 0
+    error_message = "The id_length_limit must be >= 6 if supplied (not null), or 0 for unlimited length."
+  }
 }
 
 variable "label_key_case" {
@@ -206,6 +204,7 @@ variable "label_value_case" {
   description = <<-EOT
     The letter case of output label values (also used in `tags` and `id`).
     Possible values: `lower`, `title`, `upper` and `none` (no transformation).
+    Set this to `title` and set `delimiter` to `""` to yield Pascal Case.
     Default value: `lower`.
   EOT
 

examples/complete/label1.tf

@@ -1,13 +1,13 @@
 module "label1" {
   source      = "../../"
   namespace   = "CloudPosse"
+  tenant      = "H.R.H"
   environment = "UAT"
   stage       = "build"
   name        = "Winston Churchroom"
   attributes  = ["fire", "water", "earth", "air"]
-  delimiter   = "-"
 
-  label_order = ["name", "environment", "stage", "attributes"]
+  label_order = ["name", "tenant", "environment", "stage", "attributes"]
 
   tags = {
     "City"        = "Dublin"
@@ -21,6 +21,7 @@ output "label1" {
     name       = module.label1.name
     namespace  = module.label1.namespace
     stage      = module.label1.stage
+    tenant     = module.label1.tenant
     attributes = module.label1.attributes
     delimiter  = module.label1.delimiter
   }

examples/complete/label1t1.tf

@@ -1,7 +1,7 @@
 module "label1t1" {
   source = "../../"
 
-  id_length_limit = 28
+  id_length_limit = 32
 
   context = module.label1.context
 }

examples/complete/label1t2.tf

@@ -1,7 +1,7 @@
 module "label1t2" {
   source = "../../"
 
-  id_length_limit = 29
+  id_length_limit = 33
 
   context = module.label1.context
 }

examples/complete/label2.tf

@@ -2,16 +2,16 @@ module "label2" {
   source              = "../../"
   context             = module.label1.context
   name                = "Charlie"
+  tenant              = "" # setting to `null` would have no effect
   stage               = "test"
   delimiter           = "+"
   regex_replace_chars = "/[^a-zA-Z0-9-+]/"
 
   additional_tag_map = {
-    propagate_at_launch = "true"
+    propagate_at_launch = true
     additional_tag      = "yes"
   }
 
-
   tags = {
     "City"        = "London"
     "Environment" = "Public"
@@ -24,6 +24,7 @@ output "label2" {
     name       = module.label2.name
     namespace  = module.label2.namespace
     stage      = module.label2.stage
+    tenant     = module.label2.tenant
     attributes = module.label2.attributes
     delimiter  = module.label2.delimiter
   }

examples/complete/label3c.tf

@@ -18,6 +18,7 @@ output "label3c" {
     name       = module.label3c.name
     namespace  = module.label3c.namespace
     stage      = module.label3c.stage
+    tenant     = module.label3c.tenant
     attributes = module.label3c.attributes
     delimiter  = module.label3c.delimiter
   }

examples/complete/label3n.tf

@@ -18,6 +18,7 @@ output "label3n" {
     name       = module.label3n.name
     namespace  = module.label3n.namespace
     stage      = module.label3n.stage
+    tenant     = module.label3n.tenant
     attributes = module.label3n.attributes
     delimiter  = module.label3n.delimiter
   }