Merge pull request #6016 from terraform-providers/d-iam-policy-docume…

…nts-guide

New Guide: AWS IAM Policy Documents

website/aws.erb

@@ -22,6 +22,10 @@
                             <a href="/docs/providers/aws/guides/eks-getting-started.html">AWS EKS Getting Started</a>
                         </li>
 
+                        <li<%= sidebar_current("docs-aws-guide-iam-policy-documents") %>>
+                            <a href="/docs/providers/aws/guides/iam-policy-documents.html">AWS IAM Policy Documents</a>
+                        </li>
+
                         <li<%= sidebar_current("docs-aws-guide-serverless") %>>
                             <a href="/docs/providers/aws/guides/serverless-with-aws-lambda-and-api-gateway.html">AWS Lambda with API Gateway</a>
                         </li>

website/docs/d/iam_policy_document.html.markdown

@@ -14,6 +14,8 @@ This is a data source which can be used to construct a JSON representation of
 an IAM policy document, for use with resources which expect policy documents,
 such as the `aws_iam_policy` resource.
 
+-> For more information about building AWS IAM policy documents with Terraform, see the [AWS IAM Policy Document Guide](/docs/providers/aws/guides/iam-policy-documents.html).
+
 ```hcl
 data "aws_iam_policy_document" "example" {
   statement {

website/docs/guides/iam-policy-documents.html.md

@@ -0,0 +1,169 @@
+---
+layout: "aws"
+page_title: "AWS IAM Policy Documents with Terraform"
+sidebar_current: "docs-aws-guide-iam-policy-documents"
+description: |-
+  Using Terraform to configure AWS IAM policy documents.
+---
+
+# AWS IAM Policy Documents with Terraform
+
+AWS leverages a standard JSON Identity and Access Management (IAM) policy document format across many services to control authorization to resources and API actions. This guide is designed to highlight some recommended configuration patterns with how Terraform and the AWS provider can build these policy documents.
+
+The example policy documents and resources in this guide are for illustrative purposes only. Full documentation about the IAM policy format and supported elements can be found in the [AWS IAM User Guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html).
+
+~> **NOTE:** Some AWS services only allow a subset of the policy elements or policy variables. For more information, see the AWS User Guide for the service you are configuring.
+
+~> **NOTE:** [IAM policy variables](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_variables.html), e.g. `${aws:username}`, use the same configuration syntax (`${...}`) as Terraform interpolation. When implementing IAM policy documents with these IAM variables, you may receive syntax errors from Terraform. You can escape the dollar character within your Terraform configration to prevent the error, e.g. `$${aws:username}`.
+
+<!-- TOC depthFrom:2 -->
+
+- [Choosing a Configuration Method](#choosing-a-configuration-method)
+- [Recommended Configuration Method Examples](#recommended-configuration-method-examples)
+    - [aws_iam_policy_document Data Source](#aws_iam_policy_document-data-source)
+    - [Multiple Line Heredoc Syntax](#multiple-line-heredoc-syntax)
+- [Other Configuration Method Examples](#other-configuration-method-examples)
+    - [Single Line String Syntax](#single-line-string-syntax)
+    - [file() Interpolation Function](#file-interpolation-function)
+    - [template_file Data Source](#template_file-data-source)
+
+<!-- /TOC -->
+
+## Choosing a Configuration Method
+
+Terraform offers flexibility when creating configurations to match the architectural structure of teams and infrastructure. In most situations, using native functionality within Terraform and its providers will be the simplest to understand, eliminating context switching with other tooling, file sprawl, or differing file formats. Configuration examples of the available methods can be found later in the guide.
+
+The recommended approach to building AWS IAM policy documents within Terraform is the highly customizable [`aws_iam_policy_document` data source](#aws_iam_policy_document-data-source). A short list of benefits over other methods include:
+
+- Native Terraform configuration - no need to worry about JSON formatting or syntax
+- Policy layering - create policy documents that combine and/or overwrite other policy documents
+- Built-in policy error checking
+
+Otherwise in simple cases, such as a statically defined [assume role policy for an IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_permissions-to-switch.html), Terraform's [multiple line heredoc syntax](#multiple-line-heredoc-syntax) allows the easiest formatting without any indirection of a separate data source configuration or file.
+
+Additional methods are available, such [single line string syntax](#single-line-string-syntax), the [file() interpolation function](#file-interpolation-function), and the [template_file data source](#template_file-data-source), however their usage is discouraged due to their complexity.
+
+## Recommended Configuration Method Examples
+
+These configuration methods are the simplest and most powerful within Terraform.
+
+### aws_iam_policy_document Data Source
+
+-> For complete implementation information and examples, see the [`aws_iam_policy_document` data source documentation](/docs/providers/aws/d/iam_policy_document.html).
+
+```hcl
+data "aws_iam_policy_document" "example" {
+  statement {
+    actions   = ["*"]
+    resources = ["*"]
+  }
+}
+
+resource "aws_iam_policy" "example" {
+  # ... other configuration ...
+
+  policy = "${data.aws_iam_policy_document.example.json}"
+}
+```
+
+### Multiple Line Heredoc Syntax
+
+Interpolation is available within the heredoc string if necessary.
+
+For example:
+
+```hcl
+resource "aws_iam_policy" "example" {
+  # ... other configuration ...
+  policy = <<POLICY
+{
+  "Version": "2012-10-17",
+  "Statement": {
+    "Effect": "Allow",
+    "Action": "*",
+    "Resource": "*"
+  }
+}
+POLICY
+}
+```
+
+## Other Configuration Method Examples
+
+These other configuration methods are provided only for reference and not meant to be an authoritative source of information.
+
+### Single Line String Syntax
+
+Single line IAM policy documents can be constructed with regular string syntax. Interpolation is available within the string if necessary. Since the double quotes within the IAM policy JSON conflict with Terraform's double quotes for declaring a string, they need to be escaped (`\"`).
+
+For example:
+
+```hcl
+resource "aws_iam_policy" "example" {
+  # ... other configuration ...
+
+  policy = "{\"Version\": \"2012-10-17\", \"Statement\": {\"Effect\": \"Allow\", \"Action\": \"*\", \"Resource\": \"*\"}}"
+}
+```
+
+### file() Interpolation Function
+
+To decouple the IAM policy JSON from the Terraform configuration, Terraform has a built-in [`file()` interpolation function](/docs/configuration/interpolation.html#file-path-), which can read the contents of a local file into the configuration. Interpolation is _not_ available when using the `file()` function by itself.
+
+For example, creating a file called `policy.json` with the contents:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": {
+    "Effect": "Allow",
+    "Action": "*",
+    "Resource": "*"
+  }
+}
+```
+
+Those contents can be read into the Terraform configuration via:
+
+```hcl
+resource "aws_iam_policy" "example" {
+  # ... other configuration ...
+
+  policy = "${file("policy.json")}"
+}
+```
+
+### template_file Data Source
+
+To enable interpolation in decoupled files, the [`template_file` data source](/docs/providers/template/d/file.html) is available.
+
+For example, creating a file called `policy.json.tpl` with the contents:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": {
+    "Effect": "Allow",
+    "Action": "*",
+    "Resource": "${resource}"
+  }
+}
+```
+
+Those contents can be read and interpolated into the Terraform configuration via:
+
+```hcl
+data "template_file" "example" {
+  template = "${file("policy.json.tpl")}"
+
+  vars {
+    resource = "${aws_vpc.example.arn}"
+  }
+}
+
+resource "aws_iam_policy" "example" {
+  # ... other configuration ...
+
+  policy = "${data.template_file.example.rendered}"
+}
+```

website/docs/r/api_gateway_rest_api.html.markdown

@@ -43,7 +43,7 @@ The following arguments are supported:
 * `binary_media_types` - (Optional) The list of binary media types supported by the RestApi. By default, the RestApi supports only UTF-8-encoded text payloads.
 * `minimum_compression_size` - (Optional) Minimum response size to compress for the REST API. Integer between -1 and 10485760 (10MB). Setting a value greater than -1 will enable compression, -1 disables compression (default).
 * `body` - (Optional) An OpenAPI specification that defines the set of routes and integrations to create as part of the REST API.
-* `policy` - (Optional) JSON formatted policy document that controls access to the API Gateway
+* `policy` - (Optional) JSON formatted policy document that controls access to the API Gateway. For more information about building AWS IAM policy documents with Terraform, see the [AWS IAM Policy Document Guide](/docs/providers/aws/guides/iam-policy-documents.html)
 * `api_key_source` - (Optional) The source of the API key for requests. Valid values are HEADER (default) and AUTHORIZER.
 
 __Note__: If the `body` argument is provided, the OpenAPI specification will be used to configure the resources, methods and integrations for the Rest API. If this argument is provided, the following resources should not be managed as separate ones, as updates may cause manual resource updates to be overwritten:

website/docs/r/ecr_lifecycle_policy.html.markdown

@@ -81,7 +81,7 @@ EOF
 The following arguments are supported:
 
 * `repository` - (Required) Name of the repository to apply the policy.
-* `policy` - (Required) The policy document. This is a JSON formatted string. See more details about [Policy Parameters](http://docs.aws.amazon.com/AmazonECR/latest/userguide/LifecyclePolicies.html#lifecycle_policy_parameters) in the official AWS docs.
+* `policy` - (Required) The policy document. This is a JSON formatted string. See more details about [Policy Parameters](http://docs.aws.amazon.com/AmazonECR/latest/userguide/LifecyclePolicies.html#lifecycle_policy_parameters) in the official AWS docs. For more information about building IAM policy documents with Terraform, see the [AWS IAM Policy Document Guide](/docs/providers/aws/guides/iam-policy-documents.html).
 
 ~> **NOTE:** The AWS ECR API seems to reorder rules based on `rulePriority`. If you define multiple rules that are not sorted ascending in the TF code will be flagged for recreation every `terraform plan`. 
 

website/docs/r/ecr_repository_policy.html.markdown

@@ -62,7 +62,7 @@ EOF
 The following arguments are supported:
 
 * `repository` - (Required) Name of the repository to apply the policy.
-* `policy` - (Required) The policy document. This is a JSON formatted string.
+* `policy` - (Required) The policy document. This is a JSON formatted string. For more information about building IAM policy documents with Terraform, see the [AWS IAM Policy Document Guide](/docs/providers/aws/guides/iam-policy-documents.html)
 
 ## Attributes Reference
 

website/docs/r/iam_group_policy.html.markdown

@@ -43,8 +43,7 @@ resource "aws_iam_group" "my_developers" {
 
 The following arguments are supported:
 
-* `policy` - (Required) The policy document. This is a JSON formatted string.
-  The heredoc syntax or `file` function is helpful here.
+* `policy` - (Required) The policy document. This is a JSON formatted string. For more information about building IAM policy documents with Terraform, see the [AWS IAM Policy Document Guide](/docs/providers/aws/guides/iam-policy-documents.html)
 * `name` - (Optional) The name of the policy. If omitted, Terraform will
 assign a random, unique name.
 * `name_prefix` - (Optional) Creates a unique name beginning with the specified

website/docs/r/iam_policy.html.markdown

@@ -44,10 +44,7 @@ The following arguments are supported:
 * `name_prefix` - (Optional, Forces new resource) Creates a unique name beginning with the specified prefix. Conflicts with `name`.
 * `path` - (Optional, default "/") Path in which to create the policy.
   See [IAM Identifiers](https://docs.aws.amazon.com/IAM/latest/UserGuide/Using_Identifiers.html) for more information.
-* `policy` - (Required) The policy document. This is a JSON formatted string.
-  The heredoc syntax, `file` function, or the [`aws_iam_policy_document` data
-  source](/docs/providers/aws/d/iam_policy_document.html)
-  are all helpful here.
+* `policy` - (Required) The policy document. This is a JSON formatted string. For more information about building AWS IAM policy documents with Terraform, see the [AWS IAM Policy Document Guide](/docs/providers/aws/guides/iam-policy-documents.html)
 
 ## Attributes Reference
 

website/docs/r/iam_role_policy.html.markdown

@@ -62,8 +62,7 @@ The following arguments are supported:
 assign a random, unique name.
 * `name_prefix` - (Optional) Creates a unique name beginning with the specified
   prefix. Conflicts with `name`.
-* `policy` - (Required) The policy document. This is a JSON formatted string.
-  The heredoc syntax or `file` function is helpful here.
+* `policy` - (Required) The policy document. This is a JSON formatted string. For more information about building IAM policy documents with Terraform, see the [AWS IAM Policy Document Guide](/docs/providers/aws/guides/iam-policy-documents.html)
 * `role` - (Required) The IAM role to attach to the policy.
 
 ## Attributes Reference

website/docs/r/iam_user_policy.html.markdown

@@ -47,8 +47,7 @@ resource "aws_iam_access_key" "lb" {
 
 The following arguments are supported:
 
-* `policy` - (Required) The policy document. This is a JSON formatted string.
-	The heredoc syntax or `file` function is helpful here.
+* `policy` - (Required) The policy document. This is a JSON formatted string. For more information about building AWS IAM policy documents with Terraform, see the [AWS IAM Policy Document Guide](/docs/providers/aws/guides/iam-policy-documents.html).
 * `name` - (Optional) The name of the policy. If omitted, Terraform will assign a random, unique name.
 * `name_prefix` - (Optional, Forces new resource) Creates a unique name beginning with the specified prefix. Conflicts with `name`.
 * `user` - (Required) IAM user to which to attach this policy.

website/docs/r/iot_policy.html.markdown

@@ -37,9 +37,7 @@ EOF
 The following arguments are supported:
 
 * `name` - (Required) The name of the policy.
-* `policy` - (Required) The policy document. This is a JSON formatted string.
-  The heredoc syntax or `file` function is helpful here. Use the [IoT Developer Guide]
-  (http://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html) for more information on IoT Policies
+* `policy` - (Required) The policy document. This is a JSON formatted string. Use the [IoT Developer Guide](http://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html) for more information on IoT Policies. For more information about building AWS IAM policy documents with Terraform, see the [AWS IAM Policy Document Guide](/docs/providers/aws/guides/iam-policy-documents.html).
 
 ## Attributes Reference
 

website/docs/r/kms_key.html.markdown

@@ -26,7 +26,7 @@ The following arguments are supported:
 * `description` - (Optional) The description of the key as viewed in AWS console.
 * `key_usage` - (Optional) Specifies the intended use of the key.
 	Defaults to ENCRYPT_DECRYPT, and only symmetric encryption and decryption are supported.
-* `policy` - (Optional) A valid policy JSON document.
+* `policy` - (Optional) A valid policy JSON document. For more information about building AWS IAM policy documents with Terraform, see the [AWS IAM Policy Document Guide](/docs/providers/aws/guides/iam-policy-documents.html).
 * `deletion_window_in_days` - (Optional) Duration in days after which the key is deleted
 	after destruction of the resource, must be between 7 and 30 days. Defaults to 30 days.
 * `is_enabled` - (Optional) Specifies whether the key is enabled. Defaults to true.

website/docs/r/media_store_container_policy.html.markdown

@@ -46,7 +46,7 @@ EOF
 The following arguments are supported:
 
 * `container_name` - (Required) The name of the container.
-* `policy` - (Required) The contents of the policy.
+* `policy` - (Required) The contents of the policy. For more information about building AWS IAM policy documents with Terraform, see the [AWS IAM Policy Document Guide](/docs/providers/aws/guides/iam-policy-documents.html).
 
 ## Import
 

website/docs/r/s3_bucket.html.markdown

@@ -320,7 +320,7 @@ The following arguments are supported:
 * `bucket` - (Optional, Forces new resource) The name of the bucket. If omitted, Terraform will assign a random, unique name.
 * `bucket_prefix` - (Optional, Forces new resource) Creates a unique bucket name beginning with the specified prefix. Conflicts with `bucket`.
 * `acl` - (Optional) The [canned ACL](https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl) to apply. Defaults to "private".
-* `policy` - (Optional) A valid [bucket policy](https://docs.aws.amazon.com/AmazonS3/latest/dev/example-bucket-policies.html) JSON document. Note that if the policy document is not specific enough (but still valid), Terraform may view the policy as constantly changing in a `terraform plan`. In this case, please make sure you use the verbose/specific version of the policy.
+* `policy` - (Optional) A valid [bucket policy](https://docs.aws.amazon.com/AmazonS3/latest/dev/example-bucket-policies.html) JSON document. Note that if the policy document is not specific enough (but still valid), Terraform may view the policy as constantly changing in a `terraform plan`. In this case, please make sure you use the verbose/specific version of the policy. For more information about building AWS IAM policy documents with Terraform, see the [AWS IAM Policy Document Guide](/docs/providers/aws/guides/iam-policy-documents.html).
 
 * `tags` - (Optional) A mapping of tags to assign to the bucket.
 * `force_destroy` - (Optional, Default:false ) A boolean that indicates all objects should be deleted from the bucket so that the bucket can be destroyed without error. These objects are *not* recoverable.

website/docs/r/s3_bucket_policy.html.markdown

@@ -47,4 +47,4 @@ POLICY
 The following arguments are supported:
 
 * `bucket` - (Required) The name of the bucket to which to apply the policy.
-* `policy` - (Required) The text of the policy.
+* `policy` - (Required) The text of the policy. For more information about building AWS IAM policy documents with Terraform, see the [AWS IAM Policy Document Guide](/docs/providers/aws/guides/iam-policy-documents.html).

website/docs/r/secretsmanager_secret.html.markdown

@@ -46,7 +46,7 @@ The following arguments are supported:
 * `name` - (Required) Specifies the friendly name of the new secret. The secret name can consist of uppercase letters, lowercase letters, digits, and any of the following characters: `/_+=.@-` Spaces are not permitted.
 * `description` - (Optional) A description of the secret.
 * `kms_key_id` - (Optional) Specifies the ARN or alias of the AWS KMS customer master key (CMK) to be used to encrypt the secret values in the versions stored in this secret. If you don't specify this value, then Secrets Manager defaults to using the AWS account's default CMK (the one named `aws/secretsmanager`). If the default KMS CMK with that name doesn't yet exist, then AWS Secrets Manager creates it for you automatically the first time.
-* `policy` - (Optional) A valid JSON document representing a [resource policy](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_resource-based-policies.html).
+* `policy` - (Optional) A valid JSON document representing a [resource policy](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_resource-based-policies.html). For more information about building AWS IAM policy documents with Terraform, see the [AWS IAM Policy Document Guide](/docs/providers/aws/guides/iam-policy-documents.html).
 * `recovery_window_in_days` - (Optional) Specifies the number of days that AWS Secrets Manager waits before it can delete the secret. This value can be `0` to force deletion without recovery or range from `7` to `30` days. The default value is `30`.
 * `rotation_lambda_arn` - (Optional) Specifies the ARN of the Lambda function that can rotate the secret.
 * `rotation_rules` - (Optional) A structure that defines the rotation configuration for this secret. Defined below.