feat: define iam_policy_statements object syntax

README.md

@@ -105,27 +105,38 @@ module "iam_policy" {
   # Cloud Posse recommends pinning every module to a specific version
   # version = "x.x.x"
 
-  iam_policy_statements = {
-    ListMyBucket = {
-      effect     = "Allow"
-      actions    = ["s3:ListBucket"]
-      resources  = ["arn:aws:s3:::test"]
-      conditions = []
-    }
-    WriteMyBucket = {
-      effect     = "Allow"
-      actions    = ["s3:PutObject", "s3:GetObject", "s3:DeleteObject"]
-      resources  = ["arn:aws:s3:::test/*"]
-      conditions = [
-        {
-          test     = "StringLike"
-          variable = "cloudwatch:namespace"
-          values   = ["x-*"]
-        },
-      ]
-    }
+  iam_policy = {
+    version = "2012-10-17"
+    policy_id = "example"
+    statements = [
+      {
+        sid       = "ListMyBucket"
+        effect    = "Allow"
+        actions   = ["s3:ListBucket"]
+        resources = ["arn:aws:s3:::test"]
+        conditions = [
+          {
+            test     = "StringLike"
+            variable = "cloudwatch:namespace"
+            values   = ["x-*"]
+          },
+        ]
+      },
+      {
+        sid       = "WriteMyBucket"
+        effect    = "Allow"
+        actions   = ["s3:PutObject", "s3:GetObject", "s3:DeleteObject"]
+        resources = ["arn:aws:s3:::test/*"]
+        conditions = [
+          {
+            test     = "StringLike"
+            variable = "cloudwatch:namespace"
+            values   = ["x-*"]
+          },
+        ]
+      }
+    ]
   }
-}
 
 data "aws_iam_policy_document" "assume_role" {
   statement {
@@ -177,7 +188,7 @@ Available targets:
 
 | Name | Version |
 |------|---------|
-| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.0 |
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.3.0 |
 | <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 4.0 |
 | <a name="requirement_http"></a> [http](#requirement\_http) | >= 3.0 |
 
@@ -214,12 +225,13 @@ Available targets:
 | <a name="input_descriptor_formats"></a> [descriptor\_formats](#input\_descriptor\_formats) | Describe additional descriptors to be output in the `descriptors` output map.<br>Map of maps. Keys are names of descriptors. Values are maps of the form<br>`{<br>   format = string<br>   labels = list(string)<br>}`<br>(Type is `any` so the map values can later be enhanced to provide additional options.)<br>`format` is a Terraform format string to be passed to the `format()` function.<br>`labels` is a list of labels, in order, to pass to `format()` function.<br>Label values will be normalized before being passed to `format()` so they will be<br>identical to how they appear in `id`.<br>Default is `{}` (`descriptors` output will be empty). | `any` | `{}` | 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) | ID element. Usually used for region e.g. 'uw2', 'us-west-2', OR role 'prod', 'staging', 'dev', 'UAT' | `string` | `null` | no |
-| <a name="input_iam_override_policy_documents"></a> [iam\_override\_policy\_documents](#input\_iam\_override\_policy\_documents) | List of IAM policy documents that are merged together into the exported document. In merging, statements with non-blank sids will override statements with the same sid from earlier documents in the list. Statements with non-blank sids will also override statements with the same sid from documents provided in the `source_json` and `source_policy_documents` arguments. Non-overriding statements will be added to the exported document. | `list(string)` | `null` | no |
+| <a name="input_iam_override_policy_documents"></a> [iam\_override\_policy\_documents](#input\_iam\_override\_policy\_documents) | List of IAM policy documents that are merged together into the exported document with higher precedence.<br>In merging, statements with non-blank SIDs will override statements with the same SID<br>from earlier documents in the list and from other "source" documents. | `list(string)` | `null` | no |
+| <a name="input_iam_policy"></a> [iam\_policy](#input\_iam\_policy) | IAM policy as Terraform object, compatible with `aws_iam_policy_document` except<br>that `source_policy_documents` and `override_policy_documents` are not included.<br>Use inputs `iam_source_policy_documents` and `iam_override_policy_documents` for that.<br>Conflicts with `iam_policy_statements`.<br>This can be used with or instead of the `var.iam_source_json_url`. | <pre>object({<br>    policy_id = optional(string, null)<br>    version   = optional(string, null)<br>    statements = list(object({<br>      sid           = optional(string, null)<br>      effect        = optional(string, null)<br>      actions       = optional(list(string), null)<br>      not_actions   = optional(list(string), null)<br>      resources     = optional(list(string), null)<br>      not_resources = optional(list(string), null)<br>      conditions = optional(list(object({<br>        test     = string<br>        variable = string<br>        values   = list(string)<br>      })), [])<br>      principals = optional(list(object({<br>        type        = string<br>        identifiers = list(string)<br>      })), [])<br>      not_principals = optional(list(object({<br>        type        = string<br>        identifiers = list(string)<br>      })), [])<br>    }))<br>  })</pre> | `null` | no |
 | <a name="input_iam_policy_enabled"></a> [iam\_policy\_enabled](#input\_iam\_policy\_enabled) | If set to true will create IAM policy in AWS | `bool` | `false` | no |
-| <a name="input_iam_policy_id"></a> [iam\_policy\_id](#input\_iam\_policy\_id) | ID for the policy document. | `string` | `null` | no |
-| <a name="input_iam_policy_statements"></a> [iam\_policy\_statements](#input\_iam\_policy\_statements) | Map of IAM policy statements to use in the policy. This can be used with or instead of the `var.iam_source_json_url`. | `any` | `{}` | no |
-| <a name="input_iam_source_json_url"></a> [iam\_source\_json\_url](#input\_iam\_source\_json\_url) | IAM source JSON policy to download and use as `source_json` argument. This is useful when using a 3rd party service that provides their own policy. This can be used with or instead of the `var.iam_policy_statements`. | `string` | `null` | no |
-| <a name="input_iam_source_policy_documents"></a> [iam\_source\_policy\_documents](#input\_iam\_source\_policy\_documents) | List of IAM policy documents that are merged together into the exported document. Statements defined in `source_policy_documents` or `source_json` must have unique sids. Statements with the same sid from documents assigned to the `override_json` and `override_policy_documents` arguments will override source statements. | `list(string)` | `null` | no |
+| <a name="input_iam_policy_id"></a> [iam\_policy\_id](#input\_iam\_policy\_id) | ID for the policy document when using `iam_policy_statements`. | `string` | `null` | no |
+| <a name="input_iam_policy_statements"></a> [iam\_policy\_statements](#input\_iam\_policy\_statements) | Deprecated: use `iam_policy` instead.<br>Map of IAM policy statements to use in the policy. Conflicts with `iam_policy`.<br>This can be used with or instead of the `var.iam_source_json_url`. | <pre>map(object({<br>    sid           = optional(string, null)<br>    effect        = optional(string, null)<br>    actions       = optional(list(string), null)<br>    not_actions   = optional(list(string), null)<br>    resources     = optional(list(string), null)<br>    not_resources = optional(list(string), null)<br>    conditions = optional(list(object({<br>      test     = string<br>      variable = string<br>      values   = list(string)<br>    })), [])<br>    principals = optional(list(object({<br>      type        = string<br>      identifiers = list(string)<br>    })), [])<br>    not_principals = optional(list(object({<br>      type        = string<br>      identifiers = list(string)<br>    })), [])<br>  }))</pre> | `null` | no |
+| <a name="input_iam_source_json_url"></a> [iam\_source\_json\_url](#input\_iam\_source\_json\_url) | URL of the IAM policy (in JSON format) to download and use as `source_json` argument.<br>This is useful when using a 3rd party service that provides their own policy.<br>This can be used with or instead of `var.iam_policy`. | `string` | `null` | no |
+| <a name="input_iam_source_policy_documents"></a> [iam\_source\_policy\_documents](#input\_iam\_source\_policy\_documents) | List of IAM policy documents that are merged together into the exported document.<br>Statements defined in `iam_source_policy_documents` must have unique SIDs.<br>Statements with the same SID as in statements in documents assigned to the<br>`iam_override_policy_documents` arguments will be overridden. | `list(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 keep the existing setting, which defaults to `0`.<br>Does not affect `id_full`. | `number` | `null` | no |
 | <a name="input_label_key_case"></a> [label\_key\_case](#input\_label\_key\_case) | Controls the letter case of the `tags` keys (label names) for tags generated by this module.<br>Does not affect keys of tags passed in via the `tags` input.<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 order in which the labels (ID elements) appear in the `id`.<br>Defaults to ["namespace", "environment", "stage", "name", "attributes"].<br>You can omit any of the 6 labels ("tenant" is the 6th), but at least one must be present. | `list(string)` | `null` | no |

README.yaml

@@ -77,27 +77,38 @@ usage: |-
     # Cloud Posse recommends pinning every module to a specific version
     # version = "x.x.x"
 
-    iam_policy_statements = {
-      ListMyBucket = {
-        effect     = "Allow"
-        actions    = ["s3:ListBucket"]
-        resources  = ["arn:aws:s3:::test"]
-        conditions = []
-      }
-      WriteMyBucket = {
-        effect     = "Allow"
-        actions    = ["s3:PutObject", "s3:GetObject", "s3:DeleteObject"]
-        resources  = ["arn:aws:s3:::test/*"]
-        conditions = [
-          {
-            test     = "StringLike"
-            variable = "cloudwatch:namespace"
-            values   = ["x-*"]
-          },
-        ]
-      }
+    iam_policy = {
+      version = "2012-10-17"
+      policy_id = "example"
+      statements = [
+        {
+          sid       = "ListMyBucket"
+          effect    = "Allow"
+          actions   = ["s3:ListBucket"]
+          resources = ["arn:aws:s3:::test"]
+          conditions = [
+            {
+              test     = "StringLike"
+              variable = "cloudwatch:namespace"
+              values   = ["x-*"]
+            },
+          ]
+        },
+        {
+          sid       = "WriteMyBucket"
+          effect    = "Allow"
+          actions   = ["s3:PutObject", "s3:GetObject", "s3:DeleteObject"]
+          resources = ["arn:aws:s3:::test/*"]
+          conditions = [
+            {
+              test     = "StringLike"
+              variable = "cloudwatch:namespace"
+              values   = ["x-*"]
+            },
+          ]
+        }
+      ]
     }
-  }
 
   data "aws_iam_policy_document" "assume_role" {
     statement {

docs/terraform.md

@@ -3,7 +3,7 @@
 
 | Name | Version |
 |------|---------|
-| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.0 |
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.3.0 |
 | <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 4.0 |
 | <a name="requirement_http"></a> [http](#requirement\_http) | >= 3.0 |
 
@@ -40,12 +40,13 @@
 | <a name="input_descriptor_formats"></a> [descriptor\_formats](#input\_descriptor\_formats) | Describe additional descriptors to be output in the `descriptors` output map.<br>Map of maps. Keys are names of descriptors. Values are maps of the form<br>`{<br>   format = string<br>   labels = list(string)<br>}`<br>(Type is `any` so the map values can later be enhanced to provide additional options.)<br>`format` is a Terraform format string to be passed to the `format()` function.<br>`labels` is a list of labels, in order, to pass to `format()` function.<br>Label values will be normalized before being passed to `format()` so they will be<br>identical to how they appear in `id`.<br>Default is `{}` (`descriptors` output will be empty). | `any` | `{}` | 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) | ID element. Usually used for region e.g. 'uw2', 'us-west-2', OR role 'prod', 'staging', 'dev', 'UAT' | `string` | `null` | no |
-| <a name="input_iam_override_policy_documents"></a> [iam\_override\_policy\_documents](#input\_iam\_override\_policy\_documents) | List of IAM policy documents that are merged together into the exported document. In merging, statements with non-blank sids will override statements with the same sid from earlier documents in the list. Statements with non-blank sids will also override statements with the same sid from documents provided in the `source_json` and `source_policy_documents` arguments. Non-overriding statements will be added to the exported document. | `list(string)` | `null` | no |
+| <a name="input_iam_override_policy_documents"></a> [iam\_override\_policy\_documents](#input\_iam\_override\_policy\_documents) | List of IAM policy documents that are merged together into the exported document with higher precedence.<br>In merging, statements with non-blank SIDs will override statements with the same SID<br>from earlier documents in the list and from other "source" documents. | `list(string)` | `null` | no |
+| <a name="input_iam_policy"></a> [iam\_policy](#input\_iam\_policy) | IAM policy as Terraform object, compatible with `aws_iam_policy_document` except<br>that `source_policy_documents` and `override_policy_documents` are not included.<br>Use inputs `iam_source_policy_documents` and `iam_override_policy_documents` for that.<br>Conflicts with `iam_policy_statements`.<br>This can be used with or instead of the `var.iam_source_json_url`. | <pre>object({<br>    policy_id = optional(string, null)<br>    version   = optional(string, null)<br>    statements = list(object({<br>      sid           = optional(string, null)<br>      effect        = optional(string, null)<br>      actions       = optional(list(string), null)<br>      not_actions   = optional(list(string), null)<br>      resources     = optional(list(string), null)<br>      not_resources = optional(list(string), null)<br>      conditions = optional(list(object({<br>        test     = string<br>        variable = string<br>        values   = list(string)<br>      })), [])<br>      principals = optional(list(object({<br>        type        = string<br>        identifiers = list(string)<br>      })), [])<br>      not_principals = optional(list(object({<br>        type        = string<br>        identifiers = list(string)<br>      })), [])<br>    }))<br>  })</pre> | `null` | no |
 | <a name="input_iam_policy_enabled"></a> [iam\_policy\_enabled](#input\_iam\_policy\_enabled) | If set to true will create IAM policy in AWS | `bool` | `false` | no |
-| <a name="input_iam_policy_id"></a> [iam\_policy\_id](#input\_iam\_policy\_id) | ID for the policy document. | `string` | `null` | no |
-| <a name="input_iam_policy_statements"></a> [iam\_policy\_statements](#input\_iam\_policy\_statements) | Map of IAM policy statements to use in the policy. This can be used with or instead of the `var.iam_source_json_url`. | `any` | `{}` | no |
-| <a name="input_iam_source_json_url"></a> [iam\_source\_json\_url](#input\_iam\_source\_json\_url) | IAM source JSON policy to download and use as `source_json` argument. This is useful when using a 3rd party service that provides their own policy. This can be used with or instead of the `var.iam_policy_statements`. | `string` | `null` | no |
-| <a name="input_iam_source_policy_documents"></a> [iam\_source\_policy\_documents](#input\_iam\_source\_policy\_documents) | List of IAM policy documents that are merged together into the exported document. Statements defined in `source_policy_documents` or `source_json` must have unique sids. Statements with the same sid from documents assigned to the `override_json` and `override_policy_documents` arguments will override source statements. | `list(string)` | `null` | no |
+| <a name="input_iam_policy_id"></a> [iam\_policy\_id](#input\_iam\_policy\_id) | ID for the policy document when using `iam_policy_statements`. | `string` | `null` | no |
+| <a name="input_iam_policy_statements"></a> [iam\_policy\_statements](#input\_iam\_policy\_statements) | Deprecated: use `iam_policy` instead.<br>Map of IAM policy statements to use in the policy. Conflicts with `iam_policy`.<br>This can be used with or instead of the `var.iam_source_json_url`. | <pre>map(object({<br>    sid           = optional(string, null)<br>    effect        = optional(string, null)<br>    actions       = optional(list(string), null)<br>    not_actions   = optional(list(string), null)<br>    resources     = optional(list(string), null)<br>    not_resources = optional(list(string), null)<br>    conditions = optional(list(object({<br>      test     = string<br>      variable = string<br>      values   = list(string)<br>    })), [])<br>    principals = optional(list(object({<br>      type        = string<br>      identifiers = list(string)<br>    })), [])<br>    not_principals = optional(list(object({<br>      type        = string<br>      identifiers = list(string)<br>    })), [])<br>  }))</pre> | `null` | no |
+| <a name="input_iam_source_json_url"></a> [iam\_source\_json\_url](#input\_iam\_source\_json\_url) | URL of the IAM policy (in JSON format) to download and use as `source_json` argument.<br>This is useful when using a 3rd party service that provides their own policy.<br>This can be used with or instead of `var.iam_policy`. | `string` | `null` | no |
+| <a name="input_iam_source_policy_documents"></a> [iam\_source\_policy\_documents](#input\_iam\_source\_policy\_documents) | List of IAM policy documents that are merged together into the exported document.<br>Statements defined in `iam_source_policy_documents` must have unique SIDs.<br>Statements with the same SID as in statements in documents assigned to the<br>`iam_override_policy_documents` arguments will be overridden. | `list(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 keep the existing setting, which defaults to `0`.<br>Does not affect `id_full`. | `number` | `null` | no |
 | <a name="input_label_key_case"></a> [label\_key\_case](#input\_label\_key\_case) | Controls the letter case of the `tags` keys (label names) for tags generated by this module.<br>Does not affect keys of tags passed in via the `tags` input.<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 order in which the labels (ID elements) appear in the `id`.<br>Defaults to ["namespace", "environment", "stage", "name", "attributes"].<br>You can omit any of the 6 labels ("tenant" is the 6th), but at least one must be present. | `list(string)` | `null` | no |