From 190a8a4c64edefd8018da8158f5a1398f2392f17 Mon Sep 17 00:00:00 2001
From: Radek Simko <radek.simko@gmail.com>
Date: Sat, 6 Feb 2016 23:12:27 +0000
Subject: [PATCH] provider/aws: Document how we get account ID + EC2 Role
 provider

---
 website/.bundle/config                        |  3 +-
 .../docs/providers/aws/index.html.markdown    | 39 ++++++++++++++++++-
 2 files changed, 38 insertions(+), 4 deletions(-)

diff --git a/website/.bundle/config b/website/.bundle/config
index df11c7518e0c..2fbf0ffd7101 100644
--- a/website/.bundle/config
+++ b/website/.bundle/config
@@ -1,2 +1 @@
----
-BUNDLE_DISABLE_SHARED_GEMS: '1'
+--- {}
diff --git a/website/source/docs/providers/aws/index.html.markdown b/website/source/docs/providers/aws/index.html.markdown
index 7bc328dad4cd..949c67f623ce 100644
--- a/website/source/docs/providers/aws/index.html.markdown
+++ b/website/source/docs/providers/aws/index.html.markdown
@@ -39,7 +39,7 @@ explained below:
 - Static credentials
 - Environment variables
 - Shared credentials file
-
+- EC2 Role
 
 ### Static credentials ###
 
@@ -96,6 +96,21 @@ provider "aws" {
 }
 ```
 
+###EC2 Role
+
+If you're running Terraform from an EC2 instance with IAM Instance Profile
+using IAM Role, Terraform will just ask
+[the metadata API](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html#instance-metadata-security-credentials)
+endpoint for credentials.
+
+This is a preferred approach over any other when running in EC2 as you can avoid
+hardcoding credentials. Instead these are leased on-the-fly by Terraform
+which reduces the chance of leakage.
+
+You can provide custom metadata API endpoint via `AWS_METADATA_ENDPOINT` variable
+which expects the endpoint URL including the version
+and defaults to `http://169.254.169.254:80/latest`.
+
 ## Argument Reference
 
 The following arguments are supported in the `provider` block:
@@ -156,4 +171,24 @@ Nested `endpoints` block supports the followings:
 
 * `elb` - (Optional) Use this to override the default endpoint
   URL constructed from the `region`. It's typically used to connect to
-  custom elb endpoints.
\ No newline at end of file
+  custom elb endpoints.
+
+## Getting the Account ID
+
+If you use either `allowed_account_ids` or `forbidden_account_ids`,
+Terraform uses several approaches to get the actual account ID
+in order to compare it with allowed/forbidden ones.
+
+Approaches differ per auth providers:
+
+ * EC2 instance w/ IAM Instance Profile - [Metadata API](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html)
+    is always used
+ * All other providers (ENV vars, shared creds file, ...)
+    will try two approaches in the following order
+   * `iam:GetUser` - typically useful for IAM Users. It also means
+      that each user needs to be privileged to call `iam:GetUser` for themselves.
+   * `iam:ListRoles` - this is specifically useful for IdP-federated profiles
+      which cannot use `iam:GetUser`. It also means that each federated user
+      need to be _assuming_ an IAM role which allows `iam:ListRoles`.
+      There is currently no better clean way to get account ID
+      out of the API when using federated account unfortunately.