Terraform: How to work with multiple AWS accounts

Introduction

Managing resources across multiple AWS accounts can greatly enhance your infrastructure’s security and efficiency. Terraform, an open-source infrastructure as code software tool created by HashiCorp, allows you to safely and predictably create, change, and improve infrastructure. In this tutorial, you will learn how to leverage Terraform to work with multiple AWS accounts, facilitating a more organized, scalable, and security-conscious infrastructure setup.

Before diving into the multi-account architecture, ensure you have Terraform and AWS CLI installed and configured. This tutorial assumes you have basic knowledge of both.

Understanding Terraform’s AWS Provider

The first step in managing multiple AWS accounts is to understand how the Terraform AWS provider works. It allows you to declare AWS resources in configuration files that Terraform can manage. You can specify an AWS account by using the provider block with your AWS access keys or using environment variables.

provider "aws" {
  region     = "us-east-1"
  access_key = "YOUR_ACCESS_KEY_HERE"
  secret_key = "YOUR_SECRET_KEY_HERE"
}

Using AWS AssumeRole for Multiple Accounts

The assume_role argument within the AWS provider block enables Terraform to assume an IAM role in another AWS account. This is crucial for managing resources across accounts without hardcoding credentials.

provider "aws" {
  region     = "us-east-1"
  assume_role {
    role_arn     = "arn:aws:iam::ACCOUNT_ID:role/ROLE_NAME"
    session_name = "SessionName"
  }
}

This configuration tells Terraform to assume the specified IAM role in the other account, allowing it to manage resources without directly providing access keys.

Structuring Terraform Configuration for Multi-Account Setups

Organizing your Terraform configurations is key in a multi-account setup. One common approach is using separate directories for each account or environment. This keeps your configurations clear and organized.

Example Directory Structure

./terraform
├── prod
│   ├── main.tf
│   ├── variables.tf
│   └── outputs.tf
└── dev
    ├── main.tf
    ├── variables.tf
    └── outputs.tf

Each directory represents a different AWS account or environment (prod, dev, etc.).

Using Workspaces for Environment Separation

Terraform workspaces allow you to manage state files separately for different environments. This is ideal for using the same configuration across multiple accounts/environments by switching the workspace.

terraform workspace new dev
terraform workspace select dev

After selecting the correct workspace, all Terraform operations apply to that workspace, letting you apply the same configuration across different environments with minimal changes.

Advanced: Centralizing State Management

For advanced users, managing state files in a centralized S3 bucket can further improve your multi-account strategy. This setup allows you to consolidate state management and leverage features like state locking and versioning for enhanced security and collaboration.

terraform {
  backend "s3" {
    bucket = "my-terraform-state-bucket"
    key    = "path/to/my/key"
    region = "us-east-1"
    profile = "default"
  }
}

This configuration specifies the S3 bucket where Terraform will store its state files. You’ll need to set up this bucket in an account that’s accessible to all other accounts, typically through IAM roles and policies.

Managing Multiple Configuration Versions

To handle different configurations or Terraform versions across accounts, you can use version pinning in your provider blocks. This ensures that you’re always using the correct version of the provider for each specific environment.

provider "aws" {
  version = "~> 2.0"
  ...
}

Version pinning makes your infrastructure more predictable and stable across different deployments.

Conclusion

Managing multiple AWS accounts with Terraform doesn’t have to be daunting. By understanding core concepts such as the AWS provider, leveraging AssumeRole, organizing configurations efficiently, and utilizing workspaces, you can maintain a versatile and secure multi-account infrastructure. With this knowledge, you’re well on your way to mastering Terraform’s capabilities across several AWS environments.