Managing infrastructure across multiple AWS accounts is a common scenario in cloud environments. Terraform, a popular Infrastructure as Code tool, provides a mechanism to interact with and manage resources in AWS accounts you don't directly control. This approach leverages AWS's AssumeRole functionality to enhance security and streamline cross-account resource management.
AssumeRole lets an IAM user, or another AWS service, temporarily take on the permissions of a different IAM role. This is perfect for cross-account access in Terraform. By configuring an IAM role in the target account and utilizing the assume_role block within your Terraform code, you can seamlessly provision resources without needing to directly manage credentials for the target account. This approach, combined with security best practices like the principle of least privilege and proper credential management, empowers organizations to maintain a secure and efficient multi-account AWS environment.
What AssumeRole Enables for Terraform
AssumeRole allows an IAM user to request temporary security credentials for another account, eliminating the need to manage separate credentials for each AWS account. This method, known as AssumeRole, allows an IAM user to request temporary security credentials for another account.
The core workflow configures Terraform to authenticate to Account A, request temporary credentials for Account B, and then assume a role to manage resources within Account B. The assume_role block in the aws provider tells Terraform to assume the specified role in Account B. When you run terraform apply, Terraform uses your local AWS credentials to get temporary credentials for the role in Account B. With these temporary credentials, Terraform can then create resources in the target account.
In conclusion, managing infrastructure across multiple AWS accounts is made significantly easier and more secure with Terraform's AssumeRole functionality. As your infrastructure grows, mastering Terraform's AssumeRole capabilities will prove invaluable for managing complex deployments and ensuring secure cross-account access within your AWS ecosystem.
Prerequisites for Cross-Account Access
To use Terraform to manage resources in an AWS account you don't directly control, you can leverage AWS's AssumeRole functionality.
Prerequisites include:
- Two AWS accounts, a primary account, Account A, and a target account, Account B.
- An IAM user in Account A with permissions to call sts:AssumeRole.
- Terraform installed and configured locally, or access to an HCP Terraform or Terraform Enterprise environment.
Additional prerequisites for the role setup:
- IAM Role in the Target Account: Create an IAM role in the AWS account where you want to deploy resources. This role should have the necessary permissions for Terraform to operate, e.g., create EC2 instances, S3 buckets, etc.
- Trust Policy: Configure the role's trust policy to allow your IAM user, or the service running Terraform, to assume this role.
Creating the IAM Role in the Target Account
In the AWS account you want to manage, create a new IAM role that trusts the primary account.
Procedure steps:
- Navigate to IAM > Roles > Create role in the AWS console for Account B.
- Select Another AWS account as the trusted entity type.
- Enter the Account ID of Account A.
- Optional Select the box for Require external ID to add another layer of security. This ensures that requests from Account A are only successful if they include a specific external ID that you define.
The IAM role in the target account should exist and have the correct permissions. The trust policy of the role allows your IAM user or the service running Terraform to assume the role. Your local AWS credentials have permission to assume the role.
Terraform Provider Configuration with assume_role Block
Provider configuration in Terraform code to use AssumeRole:
hcl
provider "aws" {
region = "your-target-region"
assume_role {
role_arn = "arn:aws:iam::TARGET_ACCOUNT_ID:role/YOUR_ROLE_NAME"
session_name = "TerraformSession"
}
}
Replace TARGETACCOUNTID and YOURROLENAME with the actual values. The session_name is optional, for session naming.
An alternative configuration using a profile:
hcl
provider "aws" {
region = "us-east-2"
profile = "source"
assume_role {
role_arn = "<ROLE_ARN>"
}
}
Notice that this configuration does not reference the destination profile from your AWS credentials file.
Authentication Flow and Local Credentials
Authentication relies on your existing credentials to initiate the assume role call.
- AWS CLI Credentials: Ensure your local AWS CLI is configured with credentials that have permission to assume the role you defined in your Terraform code. This is usually your regular IAM user.
- Ensure your local AWS CLI is configured with credentials for your IAM user in Account A, the user allowed to assume the role.
Terraform Execution: When you run Terraform commands, e.g., terraform apply, the AWS provider will automatically use your local AWS credentials to assume the specified role. This grants Terraform the permissions it needs in the target account.
A typical deployment workflow:
- Run terraform init to initialize the project.
- Run terraform apply to create the resource in Account B.
During apply, Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with symbols. The plan shows create operations. Do you want to perform these actions? Only 'yes' will be accepted to approve. Enter a value: yes.
After creation, outputs include rolearn = "arn:aws:iam::
Session Timeout and Security Best Practices
Important considerations:
- Security: Carefully manage the permissions granted to the IAM role being assumed.
- Session Timeout: If your Terraform operations consistently timeout, you might need to increase the session duration for the assumed role. Be mindful of the security implications of longer session durations.
Double-check the following:
- The IAM role in the target account exists and has the correct permissions.
- The trust policy of the role allows your IAM user or the service running Terraform to assume the role.
- Your local AWS credentials have permission to assume the role.
Deployment Step Summary
The following table summarizes how to use Terraform to manage resources in a different AWS account using AssumeRole:
| Step | Description | Key Points |
|---|---|---|
| 1 | Create IAM Role in Target Account | Role has permissions for Terraform operations |
| 2 | Configure Trust Policy | Allows primary account to assume role, optional external ID |
| 3 | Configure Terraform Provider | Use assumerole block with rolearn |
| 4 | Authenticate Locally | AWS CLI credentials for Account A user |
| 5 | Run Terraform | terraform init then terraform apply |
Alternatives and Complementary Patterns
Alternatives to AssumeRole:
- AWS Organizations: If you manage multiple AWS accounts within AWS Organizations, you can leverage service control policies to control access to resources across accounts.
- Terraform Workspaces: Workspaces can help manage different environments or deployments within a single Terraform configuration. However, they don't directly address cross-account access.
State Management and Documentation Tips
Additional tips for production use:
- Terraform State: When working with multiple accounts, carefully consider where you store your Terraform state. Using a shared state file can lead to conflicts. Consider using remote state storage like AWS S3 or Terraform Cloud.
- Documentation: Clearly document the IAM roles, trust policies, and Terraform configurations used for cross-account access to facilitate understanding and maintenance.
Common Troubleshooting Checklist
Before running operations:
- Verify the IAM role in the target account exists and has the correct permissions.
- Verify the trust policy allows your IAM user or the service running Terraform to assume the role.
- Verify your local AWS credentials have permission to assume the role.
If Terraform operations consistently timeout, consider adjusting the session duration for the assumed role while weighing security implications.
Conclusion
Managing infrastructure across multiple AWS accounts is made significantly easier and more secure with Terraform's AssumeRole functionality. By configuring an IAM role in the target account and utilizing the assume_role block within your Terraform code, you can seamlessly provision resources without needing to directly manage credentials for the target account. This approach, combined with security best practices like the principle of least privilege and proper credential management, empowers organizations to maintain a secure and efficient multi-account AWS environment. As your infrastructure grows, mastering Terraform's AssumeRole capabilities will prove invaluable for managing complex deployments and ensuring secure cross-account access within your AWS ecosystem.
The pattern provides temporary credentials, eliminates long-lived secrets, and centralizes access control in the target account. Proper trust policies, external IDs, session naming, and least-privilege role design remain critical to maintaining security. Paired with remote state management and clear documentation, AssumeRole enables repeatable, auditable cross-account Terraform workflows at scale.