AWS Cloud Control Provider

Use the Amazon Web Services (AWS) Cloud Control provider to interact with the many resources supported by AWS via the Cloud Control API. You must configure the provider with the proper credentials before you can use it.

Use the navigation to the left to read about the available resources.

To learn the basics of Terraform using this provider, follow the hands-on get started tutorials on HashiCorp's Learn platform.

Example Usage

Terraform 1.0.7 and later:

terraform {
  required_providers {
    awscc = {
      source  = "hashicorp/awscc"
      version = "~> 0.1"
    }
  }
}

# Configure the AWS Provider
provider "awscc" {
  region = "us-west-2"
}

# Create a Log Group
resource "awscc_logs_log_group" "example" {
  log_group_name = "example"
}

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

Static credentials can be provided by adding an access_key and secret_key in-line in the AWS provider block:

Usage:

provider "awscc" {
  region     = "us-west-2"
  access_key = "AKIAIOSFODNN7EXAMPLE"
  secret_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}

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 "awscc" {}

Usage:

$ export AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
$ export AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
$ export AWS_DEFAULT_REGION="us-west-2"
$ terraform plan

Shared Configuration and Credentials Files

You can use AWS shared configuration or credentials files to specify configuration and credentials. The default locations are $HOME/.aws/config and $HOME/.aws/credentials on Linux and macOS, or "%USERPROFILE%\.aws\config" and "%USERPROFILE%\.aws\credentials" on Windows. You can optionally specify a different location in the Terraform configuration by providing the shared_config_files and shared_credentials_files arguments or using the AWS_SHARED_CONFIG_FILE and AWS_SHARED_CREDENTIALS_FILE environment variables. This method also supports the profile configuration and corresponding AWS_PROFILE environment variable:

Usage:

provider "awscc" {
  region                   = "us-west-2"
  shared_config_files      = ["/Users/tf_user/.aws/conf"]
  shared_credentials_files = ["/Users/tf_user/.aws/creds"]
  profile                  = "customprofile"
}

Please note that the AWS Go SDK, the underlying authentication handler used by the Terraform AWS Provider, does not support all AWS CLI features.

CodeBuild, ECS, and EKS Roles

If you're running Terraform on CodeBuild or ECS and have configured an IAM Task Role, Terraform will use the container's Task Role. This support is based on the underlying AWS_CONTAINER_CREDENTIALS_RELATIVE_URI and AWS_CONTAINER_CREDENTIALS_FULL_URI environment variables being automatically set by those services or manually for advanced usage.

If you're running Terraform on EKS and have configured IAM Roles for Service Accounts (IRSA), Terraform will use the pod's role. This support is based on the underlying AWS_ROLE_ARN and AWS_WEB_IDENTITY_TOKEN_FILE environment variables being automatically set by Kubernetes or manually for advanced usage.

Custom User-Agent Information

By default, the underlying AWS client used by the Terraform AWS Provider creates requests with User-Agent headers including information about Terraform and AWS Go SDK versions. To provide additional information in the User-Agent headers, set the User-Agent product or comment information using the user_agent argument. For example,

provider "awscc" {
  user_agent = [
    {
      product_name    = "example-module"
      product_version = "1.0"
    }
    {
      product_name    = "BuildID"
      product_version = "1234"
    }
  ]
}

will append example-module/1.0 BuildID/1234 to the User-Agent.

In addition, the TF_APPEND_USER_AGENT environment variable can be set and its value will be directly added to HTTP requests. e.g.

$ export TF_APPEND_USER_AGENT="JenkinsAgent/i-12345678 BuildID/1234 (Optional Extra Information)"

EC2 Instance Metadata Service

If you're running Terraform from an EC2 instance with IAM Instance Profile using IAM Role, Terraform will query the metadata API endpoint for credentials and region.

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.

Assume Role

If provided with a role ARN, Terraform will attempt to assume this role using the supplied credentials.

Usage:

provider "awscc" {
  assume_role = {
    role_arn     = "arn:aws:iam::ACCOUNT_ID:role/ROLE_NAME"
    session_name = "SESSION_NAME"
    external_id  = "EXTERNAL_ID"
  }
}

Hands-on: Try the Use AssumeRole to Provision AWS Resources Across Accounts tutorial on HashiCorp Learn.

Assume Role Using Web Identity

If provided with a role ARN and a token from a web identity provider, the AWS Provider will attempt to assume this role using the supplied credentials.

Usage:

provider "aws" {
  assume_role_with_web_identity {
    role_arn                = "arn:aws:iam::123456789012:role/ROLE_NAME"
    session_name            = "SESSION_NAME"
    web_identity_token_file = "/Users/tf_user/secrets/web-identity-token"
  }
}

Using an External Credentials Process

To use an external process to source credentials, the process must be configured in a named profile, including the default profile. The profile is configured in a shared configuration file.

For example:

provider "aws" {
  profile = "customprofile"
}
[profile customprofile]
credential_process = custom-process --username jdoe

Schema

Optional

Nested Schema for assume_role

Required:

Optional:

Nested Schema for assume_role_with_web_identity

Required:

Optional:

Nested Schema for user_agent

Required:

Optional: