» AWS Provider
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.
Use the navigation to the left to read about the available resources.
» Example Usage
# Configure the AWS Provider
provider "aws" {
access_key = "${var.aws_access_key}"
secret_key = "${var.aws_secret_key}"
region = "us-east-1"
}
# Create a web server
resource "aws_instance" "web" {
# ...
}
» Authentication
The AWS provider offers a flexible means of providing credentials for authentication. The following methods are supported, in this order, and explained below:
- Static credentials
- Environment variables
- Shared credentials file
- EC2 Role
» Static credentials
Static credentials can be provided by adding an access_key
and secret_key
in-line in the
AWS provider block:
Usage:
provider "aws" {
region = "us-west-2"
access_key = "anaccesskey"
secret_key = "asecretkey"
}
» Environment variables
You can provide your credentials via the AWS_ACCESS_KEY_ID
and
AWS_SECRET_ACCESS_KEY
, environment variables, representing your AWS
Access Key and AWS Secret Key, respectively. Note that setting your
AWS credentials using either these (or legacy) environment variables
will override the use of AWS_SHARED_CREDENTIALS_FILE
and AWS_PROFILE
.
The AWS_DEFAULT_REGION
and AWS_SESSION_TOKEN
environment variables
are also used, if applicable:
provider "aws" {}
Usage:
$ export AWS_ACCESS_KEY_ID="anaccesskey"
$ export AWS_SECRET_ACCESS_KEY="asecretkey"
$ export AWS_DEFAULT_REGION="us-west-2"
$ terraform plan
» Shared Credentials file
You can use an AWS credentials file to specify your credentials. The
default location is $HOME/.aws/credentials
on Linux and OS X, or
"%USERPROFILE%\.aws\credentials"
for Windows users. If we fail to
detect credentials inline, or in the environment, Terraform will check
this location. You can optionally specify a different location in the
configuration by providing the shared_credentials_file
attribute, or
in the environment with the AWS_SHARED_CREDENTIALS_FILE
variable. This
method also supports a profile
configuration and matching
AWS_PROFILE
environment variable:
Usage:
provider "aws" {
region = "us-west-2"
shared_credentials_file = "/Users/tf_user/.aws/creds"
profile = "customprofile"
}
» ECS and CodeBuild Task Roles
If you're running Terraform on ECS or CodeBuild and you have configured an IAM Task Role,
Terraform will use the container's Task Role. Terraform looks for the presence of the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI
environment variable that AWS injects when a Task Role is configured. If you have not defined a Task Role for your container
or CodeBuild job, Terraform will continue to use the EC2 Role.
» 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 endpoint for credentials.
This is a preferred approach over any other when running in EC2 as you can avoid hard coding credentials. Instead these are leased on-the-fly by Terraform which reduces the chance of leakage.
You can provide the custom metadata API endpoint via the AWS_METADATA_URL
variable
which expects the endpoint URL, including the version, and defaults to http://169.254.169.254:80/latest
.
The default deadline for the EC2 metadata API endpoint is 100 milliseconds,
which can be overidden by setting the AWS_METADATA_TIMEOUT
environment
variable. The variable expects a positive golang Time.Duration string, which is
a sequence of decimal numbers and a unit suffix; valid suffixes are ns
(nanoseconds), us
(microseconds), ms
(milliseconds), s
(seconds), m
(minutes), and h
(hours). Examples of valid inputs: 100ms
, 250ms
, 1s
,
2.5s
, 2.5m
, 1m30s
.
» Assume role
If provided with a role ARN, Terraform will attempt to assume this role using the supplied credentials.
Usage:
provider "aws" {
assume_role {
role_arn = "arn:aws:iam::ACCOUNT_ID:role/ROLE_NAME"
session_name = "SESSION_NAME"
external_id = "EXTERNAL_ID"
}
}
» Argument Reference
In addition to generic provider
arguments
(e.g. alias
and version
), the following arguments are supported in the AWS
provider
block:
-
access_key
- (Optional) This is the AWS access key. It must be provided, but it can also be sourced from theAWS_ACCESS_KEY_ID
environment variable, or via a shared credentials file ifprofile
is specified. -
secret_key
- (Optional) This is the AWS secret key. It must be provided, but it can also be sourced from theAWS_SECRET_ACCESS_KEY
environment variable, or via a shared credentials file ifprofile
is specified. -
region
- (Required) This is the AWS region. It must be provided, but it can also be sourced from theAWS_DEFAULT_REGION
environment variables, or via a shared credentials file ifprofile
is specified. -
profile
- (Optional) This is the AWS profile name as set in the shared credentials file. -
assume_role
- (Optional) Anassume_role
block (documented below). Only oneassume_role
block may be in the configuration. -
endpoints
- (Optional) Configuration block for customizing service endpoints. See the Custom Service Endpoints Guide for more information about connecting to alternate AWS endpoints or AWS compatible solutions. -
shared_credentials_file
= (Optional) This is the path to the shared credentials file. If this is not set and a profile is specified,~/.aws/credentials
will be used. -
token
- (Optional) Session token for validating temporary credentials. Typically provided after successful identity federation or Multi-Factor Authentication (MFA) login. With MFA login, this is the session token provided afterwards, not the 6 digit MFA code used to get temporary credentials. It can also be sourced from theAWS_SESSION_TOKEN
environment variable. -
max_retries
- (Optional) This is the maximum number of times an API call is retried, in the case where requests are being throttled or experiencing transient failures. The delay between the subsequent API calls increases exponentially. -
allowed_account_ids
- (Optional) List of allowed, white listed, AWS account IDs to prevent you from mistakenly using an incorrect one (and potentially end up destroying a live environment). Conflicts withforbidden_account_ids
. -
forbidden_account_ids
- (Optional) List of forbidden, blacklisted, AWS account IDs to prevent you mistakenly using a wrong one (and potentially end up destroying a live environment). Conflicts withallowed_account_ids
. -
insecure
- (Optional) Explicitly allow the provider to perform "insecure" SSL requests. If omitted, default value isfalse
. -
skip_credentials_validation
- (Optional) Skip the credentials validation via the STS API. Useful for AWS API implementations that do not have STS available or implemented. -
skip_get_ec2_platforms
- (Optional) Skip getting the supported EC2 platforms. Used by users that don't have ec2:DescribeAccountAttributes permissions. -
skip_region_validation
- (Optional) Skip validation of provided region name. Useful for AWS-like implementations that use their own region names or to bypass the validation for regions that aren't publicly available yet. -
skip_requesting_account_id
- (Optional) Skip requesting the account ID. Useful for AWS API implementations that do not have the IAM, STS API, or metadata API. When set totrue
and not determined previously, returns an empty account ID when manually constructing ARN attributes with the following:-
aws_api_gateway_deployment
resource -
aws_api_gateway_rest_api
resource -
aws_api_gateway_stage
resource -
aws_budgets_budget
resource -
aws_cognito_identity_pool
resource -
aws_cognito_user_pool
resource -
aws_cognito_user_pools
data source -
aws_dms_replication_subnet_group
resource -
aws_dx_connection
resource -
aws_dx_hosted_private_virtual_interface_accepter
resource -
aws_dx_hosted_private_virtual_interface
resource -
aws_dx_hosted_public_virtual_interface_accepter
resource -
aws_dx_hosted_public_virtual_interface
resource -
aws_dx_lag
resource -
aws_dx_private_virtual_interface
resource -
aws_dx_public_virtual_interface
resource -
aws_ebs_volume
data source -
aws_ecs_cluster
resource (import) -
aws_ecs_service
resource (import) -
aws_efs_file_system
data source -
aws_efs_file_system
resource -
aws_efs_mount_target
data source -
aws_efs_mount_target
resource -
aws_elasticache_cluster
data source -
aws_elasticache_cluster
resource -
aws_elb
resource -
aws_glue_crawler
resource -
aws_instance
data source -
aws_instance
resource -
aws_launch_template
resource -
aws_redshift_cluster
resource -
aws_redshift_subnet_group
resource -
aws_s3_account_public_access_block
resource -
aws_ses_domain_identity_verification
resource -
aws_ses_domain_identity
resource -
aws_ssm_document
resource -
aws_ssm_parameter
resource -
aws_vpc
data source -
aws_vpc
resource -
aws_waf_ipset
resource -
aws_wafregional_ipset
resource
-
-
skip_metadata_api_check
- (Optional) Skip the AWS Metadata API check. Useful for AWS API implementations that do not have a metadata API endpoint. Setting totrue
prevents Terraform from authenticating via the Metadata API. You may need to use other authentication methods like static credentials, configuration variables, or environment variables. -
s3_force_path_style
- (Optional) Set this totrue
to force the request to use path-style addressing, i.e.,http://s3.amazonaws.com/BUCKET/KEY
. By default, the S3 client will use virtual hosted bucket addressing,http://BUCKET.s3.amazonaws.com/KEY
, when possible. Specific to the Amazon S3 service.
The nested assume_role
block supports the following:
-
role_arn
- (Required) The ARN of the role to assume. -
session_name
- (Optional) The session name to use when making the AssumeRole call. -
external_id
- (Optional) The external ID to use when making the AssumeRole call. -
policy
- (Optional) A more restrictive policy to apply to the temporary credentials. This gives you a way to further restrict the permissions for the resulting temporary security credentials. You cannot use the passed policy to grant permissions that are in excess of those allowed by the access policy of the role that is being assumed.
» 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 or forbidden IDs.
Approaches differ per authentication providers:
- EC2 instance w/ IAM Instance Profile - Metadata API
is always used. Introduced in Terraform
0.6.16
. - All other providers (environment variable, shared credentials 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 calliam:GetUser
for themselves. -
sts:GetCallerIdentity
- Should work for both IAM Users and federated IAM Roles, introduced in Terraform0.6.16
. -
iam:ListRoles
- This is specifically useful for IdP-federated profiles which cannot useiam:GetUser
. It also means that each federated user need to be assuming an IAM role which allowsiam:ListRoles
. Used in Terraform0.6.16+
. There used to be no better way to get account ID out of the API when using federated account untilsts:GetCallerIdentity
was introduced.
-