github.com/recobe182/terraform@v0.8.5-0.20170117231232-49ab22a935b7/website/source/docs/providers/aws/index.html.markdown (about)

     1  ---
     2  layout: "aws"
     3  page_title: "Provider: AWS"
     4  sidebar_current: "docs-aws-index"
     5  description: |-
     6    The Amazon Web Services (AWS) provider is used to interact with the many resources supported by AWS. The provider needs to be configured with the proper credentials before it can be used.
     7  ---
     8  
     9  # AWS Provider
    10  
    11  The Amazon Web Services (AWS) provider is used to interact with the
    12  many resources supported by AWS. The provider needs to be configured
    13  with the proper credentials before it can be used.
    14  
    15  Use the navigation to the left to read about the available resources.
    16  
    17  ## Example Usage
    18  
    19  ```
    20  # Configure the AWS Provider
    21  provider "aws" {
    22      access_key = "${var.aws_access_key}"
    23      secret_key = "${var.aws_secret_key}"
    24      region = "us-east-1"
    25  }
    26  
    27  # Create a web server
    28  resource "aws_instance" "web" {
    29      ...
    30  }
    31  ```
    32  
    33  ## Authentication
    34  
    35  The AWS provider offers a flexible means of providing credentials for
    36  authentication. The following methods are supported, in this order, and
    37  explained below:
    38  
    39  - Static credentials
    40  - Environment variables
    41  - Shared credentials file
    42  - EC2 Role
    43  
    44  ### Static credentials ###
    45  
    46  Static credentials can be provided by adding an `access_key` and `secret_key` in-line in the
    47  AWS provider block:
    48  
    49  Usage:
    50  
    51  ```
    52  provider "aws" {
    53    region     = "us-west-2"
    54    access_key = "anaccesskey"
    55    secret_key = "asecretkey"
    56  }
    57  ```
    58  
    59  ### Environment variables
    60  
    61  You can provide your credentials via the `AWS_ACCESS_KEY_ID` and
    62  `AWS_SECRET_ACCESS_KEY`, environment variables, representing your AWS
    63  Access Key and AWS Secret Key, respectively.  The `AWS_DEFAULT_REGION`
    64  and `AWS_SESSION_TOKEN` environment variables are also used, if
    65  applicable:
    66  
    67  ```
    68  provider "aws" {}
    69  ```
    70  
    71  Usage:
    72  
    73  ```
    74  $ export AWS_ACCESS_KEY_ID="anaccesskey"
    75  $ export AWS_SECRET_ACCESS_KEY="asecretkey"
    76  $ export AWS_DEFAULT_REGION="us-west-2"
    77  $ terraform plan
    78  ```
    79  
    80  ### Shared Credentials file
    81  
    82  You can use an AWS credentials file to specify your credentials. The
    83  default location is `$HOME/.aws/credentials` on Linux and OS X, or
    84  `"%USERPROFILE%\.aws\credentials"` for Windows users. If we fail to
    85  detect credentials inline, or in the environment, Terraform will check
    86  this location. You can optionally specify a different location in the
    87  configuration by providing the `shared_credentials_file` attribute, or
    88  in the environment with the `AWS_SHARED_CREDENTIALS_FILE` variable. This
    89  method also supports a `profile` configuration and matching
    90  `AWS_PROFILE` environment variable:
    91  
    92  Usage:
    93  
    94  ```
    95  provider "aws" {
    96    region                   = "us-west-2"
    97    shared_credentials_file  = "/Users/tf_user/.aws/creds"
    98    profile                  = "customprofile"
    99  }
   100  ```
   101  
   102  ### EC2 Role
   103  
   104  If you're running Terraform from an EC2 instance with IAM Instance Profile
   105  using IAM Role, Terraform will just ask
   106  [the metadata API](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html#instance-metadata-security-credentials)
   107  endpoint for credentials.
   108  
   109  This is a preferred approach over any other when running in EC2 as you can avoid
   110  hard coding credentials. Instead these are leased on-the-fly by Terraform
   111  which reduces the chance of leakage.
   112  
   113  You can provide the custom metadata API endpoint via the `AWS_METADATA_ENDPOINT` variable
   114  which expects the endpoint URL, including the version, and defaults to `http://169.254.169.254:80/latest`.
   115  
   116  ### Assume role
   117  
   118  If provided with a role ARN, Terraform will attempt to assume this role
   119  using the supplied credentials.
   120  
   121  Usage:
   122  
   123  ```
   124  provider "aws" {
   125    assume_role {
   126      role_arn = "arn:aws:iam::ACCOUNT_ID:role/ROLE_NAME"
   127      session_name = "SESSION_NAME"
   128      external_id = "EXTERNAL_ID"
   129    }
   130  }
   131  ```
   132  
   133  ## Argument Reference
   134  
   135  The following arguments are supported in the `provider` block:
   136  
   137  * `access_key` - (Optional) This is the AWS access key. It must be provided, but
   138    it can also be sourced from the `AWS_ACCESS_KEY_ID` environment variable, or via
   139    a shared credentials file if `profile` is specified.
   140  
   141  * `secret_key` - (Optional) This is the AWS secret key. It must be provided, but
   142    it can also be sourced from the `AWS_SECRET_ACCESS_KEY` environment variable, or
   143    via a shared credentials file if `profile` is specified.
   144  
   145  * `region` - (Required) This is the AWS region. It must be provided, but
   146    it can also be sourced from the `AWS_DEFAULT_REGION` environment variables, or
   147    via a shared credentials file if `profile` is specified.
   148  
   149  * `profile` - (Optional) This is the AWS profile name as set in the shared credentials
   150    file.
   151  
   152  * `assume_role` - (Optional) An `assume_role` block (documented below). Only one
   153    `assume_role` block may be in the configuration.
   154  
   155  * `shared_credentials_file` = (Optional) This is the path to the shared credentials file.
   156    If this is not set and a profile is specified, `~/.aws/credentials` will be used.
   157  
   158  * `token` - (Optional) Use this to set an MFA token. It can also be sourced
   159    from the `AWS_SESSION_TOKEN` environment variable.
   160  
   161  * `max_retries` - (Optional) This is the maximum number of times an API
   162    call is retried, in the case where requests are being throttled or
   163    experiencing transient failures. The delay between the subsequent API
   164    calls increases exponentially.
   165  
   166  * `allowed_account_ids` - (Optional) List of allowed, white listed, AWS
   167    account IDs to prevent you from mistakenly using an incorrect one (and
   168    potentially end up destroying a live environment). Conflicts with
   169    `forbidden_account_ids`.
   170  
   171  * `forbidden_account_ids` - (Optional) List of forbidden, blacklisted,
   172    AWS account IDs to prevent you mistakenly using a wrong one (and
   173    potentially end up destroying a live environment). Conflicts with
   174    `allowed_account_ids`.
   175  
   176  * `insecure` - (Optional) Explicitly allow the provider to
   177    perform "insecure" SSL requests. If omitted, default value is `false`.
   178  
   179  * `dynamodb_endpoint` - (Optional) Use this to override the default endpoint
   180    URL constructed from the `region`. It's typically used to connect to
   181    `dynamodb-local`.
   182  
   183  * `kinesis_endpoint` - (Optional) Use this to override the default endpoint
   184    URL constructed from the `region`. It's typically used to connect to
   185    `kinesalite`.
   186  
   187  * `skip_credentials_validation` - (Optional) Skip the credentials
   188    validation via the STS API. Useful for AWS API implementations that do
   189    not have STS available or implemented.
   190  
   191  * `skip_requesting_account_id` - (Optional) Skip requesting the account
   192    ID.  Useful for AWS API implementations that do not have the IAM, STS
   193    API, or metadata API.  When set to `true`, prevents you from managing
   194    any resource that requires Account ID to construct an ARN, e.g.
   195    - `aws_db_instance`
   196    - `aws_db_option_group`
   197    - `aws_db_parameter_group`
   198    - `aws_db_security_group`
   199    - `aws_db_subnet_group`
   200    - `aws_elasticache_cluster`
   201    - `aws_glacier_vault`
   202    - `aws_rds_cluster`
   203    - `aws_rds_cluster_instance`
   204    - `aws_rds_cluster_parameter_group`
   205    - `aws_redshift_cluster`
   206  
   207  * `skip_metadata_api_check` - (Optional) Skip the AWS Metadata API
   208    check.  Useful for AWS API implementations that do not have a metadata
   209    API endpoint.  Setting to `true` prevents Terraform from authenticating
   210    via the Metadata API. You may need to use other authentication methods
   211    like static credentials, configuration variables, or environment
   212    variables.
   213  
   214  * `s3_force_path_style` - (Optional) Set this to `true` to force the
   215    request to use path-style addressing, i.e.,
   216    `http://s3.amazonaws.com/BUCKET/KEY`. By default, the S3 client will use
   217    virtual hosted bucket addressing, `http://BUCKET.s3.amazonaws.com/KEY`,
   218    when possible. Specific to the Amazon S3 service.
   219  
   220  The nested `assume_role` block supports the following:
   221  
   222  * `role_arn` - (Required) The ARN of the role to assume.
   223  
   224  * `session_name` - (Optional) The session name to use when making the
   225    AssumeRole call.
   226  
   227  * `external_id` - (Optional) The external ID to use when making the
   228    AssumeRole call.
   229  
   230  Nested `endpoints` block supports the following:
   231  
   232  * `iam` - (Optional) Use this to override the default endpoint
   233    URL constructed from the `region`. It's typically used to connect to
   234    custom IAM endpoints.
   235  
   236  * `ec2` - (Optional) Use this to override the default endpoint
   237    URL constructed from the `region`. It's typically used to connect to
   238    custom EC2 endpoints.
   239  
   240  * `elb` - (Optional) Use this to override the default endpoint
   241    URL constructed from the `region`. It's typically used to connect to
   242    custom ELB endpoints.
   243  
   244  * `s3` - (Optional) Use this to override the default endpoint
   245    URL constructed from the `region`. It's typically used to connect to
   246    custom S3 endpoints.
   247  
   248  ## Getting the Account ID
   249  
   250  If you use either `allowed_account_ids` or `forbidden_account_ids`,
   251  Terraform uses several approaches to get the actual account ID
   252  in order to compare it with allowed or forbidden IDs.
   253  
   254  Approaches differ per authentication providers:
   255  
   256   * EC2 instance w/ IAM Instance Profile - [Metadata API](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html)
   257      is always used. Introduced in Terraform `0.6.16`.
   258   * All other providers (environment variable, shared credentials file, ...)
   259      will try two approaches in the following order
   260     * `iam:GetUser` - Typically useful for IAM Users. It also means
   261        that each user needs to be privileged to call `iam:GetUser` for themselves.
   262     * `sts:GetCallerIdentity` - _Should_ work for both IAM Users and federated IAM Roles,
   263        introduced in Terraform `0.6.16`.
   264     * `iam:ListRoles` - This is specifically useful for IdP-federated profiles
   265        which cannot use `iam:GetUser`. It also means that each federated user
   266        need to be _assuming_ an IAM role which allows `iam:ListRoles`.
   267        Used in Terraform `0.6.16+`.
   268        There used to be no better way to get account ID out of the API
   269        when using federated account until `sts:GetCallerIdentity` was introduced.