Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

New Guide: AWS IAM Policy Documents #6016

Merged
merged 2 commits into from
Oct 5, 2018
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions website/aws.erb
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
2 changes: 2 additions & 0 deletions website/docs/d/iam_policy_document.html.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
169 changes: 169 additions & 0 deletions website/docs/guides/iam-policy-documents.html.md
Original file line number Diff line number Diff line change
@@ -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 staticly defined assume role policy for an IAM role, 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

staticly -> statically

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also it may be worth linking to a document/docs page which explains what is "assume role policy".
AFAIK it often causes some confusion for IAM beginners as they mismatch that with the actual resource policy.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.


Additional methods are possible, 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

are possible -> are available? Admittedly I'm not a native english speaker, but "available methods" sounds a bit more natural compared to "possible methods". Feel free to ignore this though.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍 that's a good catch


## 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we link to any doc page which explains HEREDOC? I'm not sure if we have such page in our docs 🤔

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Turns out the 0.12 branch has a whole section on it! https://github.com/hashicorp/terraform/blob/v0.12-dev/website/docs/configuration/expressions.html.md#string-literals

Unfortunately the current documentation has it listed as just a bullet point under syntax 😅 https://www.terraform.io/docs/configuration/syntax.html (which will be removed with 0.12 documentation updates)

Not sure if we link to the soon-to-be removed place or somewhere else. Open to opinions!


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, in a file called `policy.json`:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We seem to be missing a verb here ^ 👓


```json
{
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "*",
"Resource": "*"
}
}
```

Then `policy.json` 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, in a file called `policy.json.tpl`:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We seem to be missing a verb here ^ 👓


```json
{
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "*",
"Resource": "${resource}"
}
}
```

The 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}"
}
```
2 changes: 1 addition & 1 deletion website/docs/r/api_gateway_rest_api.html.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion website/docs/r/ecr_lifecycle_policy.html.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand Down
2 changes: 1 addition & 1 deletion website/docs/r/ecr_repository_policy.html.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
3 changes: 1 addition & 2 deletions website/docs/r/iam_group_policy.html.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 1 addition & 4 deletions website/docs/r/iam_policy.html.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
3 changes: 1 addition & 2 deletions website/docs/r/iam_role_policy.html.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 1 addition & 2 deletions website/docs/r/iam_user_policy.html.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 1 addition & 3 deletions website/docs/r/iot_policy.html.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion website/docs/r/kms_key.html.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion website/docs/r/media_store_container_policy.html.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion website/docs/r/s3_bucket.html.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion website/docs/r/s3_bucket_policy.html.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -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).
2 changes: 1 addition & 1 deletion website/docs/r/secretsmanager_secret.html.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading