Managing infrastructure across multiple AWS accounts is a common requirement for organizations seeking to enhance security, separation of concerns, or compliance. Terraform, a popular Infrastructure as Code tool, provides robust capabilities to streamline this process. This article outlines essential practices for effectively managing multiple AWS accounts using Terraform, enabling you to orchestrate resources seamlessly across your environments.
Multi-Account Architecture Fundamentals
Multi-account setups provide security isolation with blast radius containment, billing separation for clear cost attribution, compliance for regulatory requirements, and resource limits to avoid hitting AWS quotas.
A typical AWS Organization structure includes a Management Account where Terraform runs, Production Account with Production VPC and Production RDS, Staging Account with Staging VPC and Staging RDS, and Shared Services with Central Logging and Shared ECR. The Terraform Runner assumes role into each target account.
The guide is designed for DevOps engineers, cloud architects, and infrastructure teams who need to scale beyond single-account deployments. Basic Terraform experience and AWS fundamentals are assumed, with advanced concepts covered that make multi-account architecture successful.
Provider Aliases and Resource Targeting
Utilize multiple provider configurations by defining separate provider blocks within your Terraform configuration file for each AWS account you want to target. Each provider block should have a unique alias assigned to it.
hcl
provider "aws" {
region = "us-west-2"
alias = "dev"
}
provider "aws" {
region = "us-east-1"
alias = "prod"
}
Provider aliases define separate provider blocks for each AWS account, assigning a unique alias to each e.g., aws.dev, aws.prod.
Resource Targeting uses the provider argument within resource blocks to specify the target AWS account using its alias.
hcl
resource "aws_instance" "dev_instance" {
ami = "ami-0c94855ba95c574c8"
instance_type = "t2.micro"
provider = aws.dev
}
resource "aws_instance" "prod_instance" {
ami = "ami-0c94855ba95c574c8"
instance_type = "t2.micro"
provider = aws.prod
}
When defining resources that should be deployed to a specific AWS account, reference the corresponding provider alias using the provider argument within the resource block.
A financial services company needs to maintain strict separation between their development and production environments for compliance reasons. Each environment resides in a separate AWS account, but the infrastructure team wants to manage both using a single Terraform codebase to ensure consistency and reduce operational overhead.
The complete code for this tutorial is available on GitHub.
Authentication and Cross-Account Access
Implement authentication for each account by ensuring that you have configured appropriate AWS credentials for each provider alias.
Authentication is configured using environment variables, profiles, etc., for each provider alias.
The solution uses multiple AWS provider configurations within a single Terraform project. Each provider instance authenticates to a different AWS account using IAM roles and the AssumeRole capability.
Key components include Execution Account where Terraform executes.
Setting up cross-account IAM roles is the most common pattern using provider aliases with IAM role assumption.
```hcl
In target account: iam-role.tf
resource "awsiamrole" "terraformdeploy" {
name = "TerraformDeployRole"
assumerolepolicy = jsonencode({
Version = "2012-10-17"
Statement = [
{
Effect = "Allow"
Principal = {
AWS = "arn:aws:iam::${var.managementaccountid}:root"
}
Action = "sts:AssumeRole"
Condition = {
StringEquals = {
"sts:ExternalId" = var.externalid
}
}
}
]
})
}
resource "awsiamrolepolicyattachment" "terraformdeploy" {
role = awsiamrole.terraformdeploy.name
policy_arn = "arn:aws:iam:aws:policy/AdministratorAccess"
}
```
Leverage IAM roles and assume roles for resources requiring interaction across accounts. Adhere to security best practices, like the principle of least privilege, when configuring IAM roles and policies.
Code Organization and State Management
Structure code modularly, using modules to encapsulate resources for specific accounts or environments.
Code Organization best practices include:
- Item
- Item
- Item
Remote State Management utilizes a shared state backend e.g., AWS S3 for collaboration and consistency.
Terraform state management best practices keep deployments organized across accounts and regions without conflicts.
Terraform modules scalability can be built into infrastructure from day one.
Custom modules for cross-account interactions develop reusable modules that encapsulate the logic for cross-account resource provisioning and management, such as creating IAM roles and policies.
This is useful for sharing information like VPC IDs or security group rules.
| Practice | Purpose |
|---|---|
| Provider Aliases | Separate provider blocks per account |
| Resource Targeting | Provider argument per resource |
| Remote State | S3 backend for collaboration |
| Modules | Encapsulate per account/environment |
Multi-Region Infrastructure Strategies
Managing infrastructure across multiple AWS accounts and regions can feel overwhelming, but Terraform makes it manageable with the right approach.
You will master terraform state management best practices that keep your deployments organized across accounts and regions without conflicts.
Provider configuration techniques handle authentication seamlessly across environments.
Multi region infrastructure terraform strategies include provider configuration techniques that handle authentication seamlessly across environments.
CI/CD Pipeline Integration
Terraform CI/CD pipeline integration and troubleshooting techniques solve real-world challenges teams face when managing complex multi-account deployments.
Deploy terraform to multiple AWS accounts requires:
- An existing AWS CodeCommit repository OR an AWS CodeConnection connection to the third-party source and repo of your choice
- Remote state that the pipeline can access
- A cross-account IAM role in the target accounts, that can be assumed by the pipeline
- Optional compatibility with Terraform Workspaces if you wish to change variables between accounts
A cross-account IAM role in the target accounts can be assumed by the pipeline using the CodeBuild IAM Role.
Terraform Cloud/Enterprise explores features offered for enhanced collaboration, governance, and remote execution capabilities in multi-account environments.
Security and Best Practices
Security isolation provides blast radius containment.
Best practices include:
- Utilize multiple provider configurations with unique alias per account
- Leverage provider aliases for resource targeting
- Implement authentication for each account
- Structure code modularly with modules
- Utilize shared state backend
- Leverage IAM roles and assume roles for cross-account access
- Adhere to principle of least privilege for IAM roles and policies
- Thorough Testing in staging environment before deploying to production
By following these practices, you can effectively manage infrastructure across multiple AWS accounts with Terraform, ensuring clarity, maintainability, and security.
By implementing these strategies and adapting provided code snippets to specific needs, you can leverage Terraform's power to manage infrastructure across multiple AWS accounts effectively.
Troubleshooting and Debugging
Terraform console utilizes terraform console to experiment with provider configurations, data sources, and expressions to validate code before deployment.
Verbose logging enables verbose logging in Terraform and AWS to gain detailed insights into API calls, resource changes, and potential errors.
Resource dependency visualization uses terraform graph command to visualize dependencies between resources across different accounts, aiding in understanding and troubleshooting deployment issues.
Conclusion
Managing infrastructure across multiple AWS accounts with Terraform requires deliberate provider alias design, robust cross-account authentication via IAM roles and AssumeRole, and disciplined state and code organization. Provider aliases enable precise resource targeting to dev, prod, or shared services accounts from a single codebase. Authentication must be configured per alias with appropriate credentials and role assumption to maintain security boundaries. Modular code structure combined with a shared remote state backend ensures consistency and collaboration across teams. CI/CD pipeline integration with CodeBuild, CodeCommit, or CodeConnection and cross-account roles enables safe, repeatable deployments. Security best practices, thorough testing in staging, and troubleshooting tools like terraform console, verbose logging, and terraform graph complete a production-ready multi-account workflow. Following these patterns allows organizations to achieve security isolation, billing separation, and compliance while maintaining a single source of truth for infrastructure.