DEV Community

Manoj Kumar Kagitha
Manoj Kumar Kagitha

Posted on

Multi-Cloud Terraform: One Codebase, Three Clouds

Every few years, someone proposes running everything on every cloud. The pitch is resilience and bargaining power. The reality is three times the state files, three times the pipelines, and three sets of cloud quirks living in your head. Multi-cloud with Terraform is absolutely doable. Whether you should do it is a separate question, and this post answers both.

We will cover provider aliases, the module abstraction pattern that actually works, where abstractions break down, CI/CD across clouds, a realistic repo layout, and the operational reality check nobody puts in the sales deck.

Why teams go multi-cloud

The legitimate reasons, in rough order of how often they hold up:

  1. Residency and compliance. A regulator or a customer contract requires data in a specific cloud or region. This is the strongest reason. It is not a choice.
  2. Resilience. Surviving a cloud-wide outage. Real, but expensive, and most teams overestimate both the likelihood and their ability to fail over cleanly.
  3. Best of breed. One cloud's managed database, another's ML platform. Valid for specific workloads, painful as a general strategy.
  4. Bargaining power. Threatening to leave gets you a discount. Actually leaving costs more than the discount.

If your reason is number 4, or "our architect read a blog post," stop here. The rest of this post is for teams with a real requirement.

Provider aliases: the mechanics

Terraform supports multiple instances of the same provider through aliases. This is how you target two regions, or two accounts, from one configuration:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

# Default: primary region
provider "aws" {
  region = "us-east-1"
}

# Alias: DR region
provider "aws" {
  alias  = "west"
  region = "us-west-2"
}

resource "aws_s3_bucket" "primary" {
  bucket = "myorg-data-primary"
}

resource "aws_s3_bucket" "dr" {
  provider = aws.west
  bucket   = "myorg-data-dr"
}
Enter fullscreen mode Exit fullscreen mode

Aliases also span accounts. Assume a role in each account:

provider "aws" {
  alias  = "prod"
  region = "us-east-1"
  assume_role {
    role_arn = "arn:aws:iam::111122223333:role/terraform-prod"
  }
}

provider "aws" {
  alias  = "staging"
  region = "us-east-1"
  assume_role {
    role_arn = "arn:aws:iam::444455556666:role/terraform-staging"
  }
}
Enter fullscreen mode Exit fullscreen mode

Modules accept providers explicitly:

module "network_prod" {
  source = "./modules/network"
  providers = {
    aws = aws.prod
  }
  cidr_block = "10.1.0.0/16"
}

module "network_staging" {
  source = "./modules/network"
  providers = {
    aws = aws.staging
  }
  cidr_block = "10.2.0.0/16"
}
Enter fullscreen mode Exit fullscreen mode

This is the easy part. The hard part is not syntax. It is deciding what "the same" means across clouds that are not the same.

The abstraction pattern that works

The pattern that survives contact with reality: one module per cloud, identical inputs, cloud-specific internals.

You do not write one module that provisions "a network" on any cloud. You write three modules with the same interface:

modules/
  network-aws/
    main.tf
    variables.tf
    outputs.tf
  network-azure/
    main.tf
    variables.tf
    outputs.tf
  network-gcp/
    main.tf
    variables.tf
    outputs.tf
Enter fullscreen mode Exit fullscreen mode

Same variables in, same outputs out. Different resources inside.

# modules/network-aws/variables.tf
variable "name" {
  type        = string
  description = "Base name for network resources"
}

variable "cidr_block" {
  type        = string
  description = "Primary CIDR for the VPC"
}

variable "availability_zones" {
  type        = list(string)
  description = "AZs to spread subnets across"
}

variable "environment" {
  type        = string
  description = "Environment label for tagging"
}
Enter fullscreen mode Exit fullscreen mode
# modules/network-aws/outputs.tf
output "network_id" {
  value       = aws_vpc.main.id
  description = "VPC ID"
}

output "private_subnet_ids" {
  value       = aws_subnet.private[*].id
  description = "Private subnet IDs"
}

output "public_subnet_ids" {
  value       = aws_subnet.public[*].id
  description = "Public subnet IDs"
}
Enter fullscreen mode Exit fullscreen mode
# modules/network-azure/variables.tf: identical inputs
variable "name" {
  type        = string
  description = "Base name for network resources"
}

variable "cidr_block" {
  type        = string
  description = "Primary CIDR for the VNet"
}

variable "availability_zones" {
  type        = list(string)
  description = "Zones to spread subnets across"
}

variable "environment" {
  type        = string
  description = "Environment label for tagging"
}
Enter fullscreen mode Exit fullscreen mode
# modules/network-azure/outputs.tf: identical outputs
output "network_id" {
  value       = azurerm_virtual_network.main.id
  description = "VNet ID"
}

output "private_subnet_ids" {
  value       = azurerm_subnet.private[*].id
  description = "Private subnet IDs"
}

output "public_subnet_ids" {
  value       = azurerm_subnet.public[*].id
  description = "Public subnet IDs"
}
Enter fullscreen mode Exit fullscreen mode

The calling code does not care which cloud it is:

# envs/prod-aws/main.tf
module "network" {
  source             = "../../modules/network-aws"
  name               = "prod"
  cidr_block         = "10.1.0.0/16"
  availability_zones = ["us-east-1a", "us-east-1b", "us-east-1c"]
  environment        = "prod"
}
Enter fullscreen mode Exit fullscreen mode
# envs/prod-azure/main.tf
module "network" {
  source             = "../../modules/network-azure"
  name               = "prod"
  cidr_block         = "10.1.0.0/16"
  availability_zones = ["1", "2", "3"]
  environment        = "prod"
}
Enter fullscreen mode Exit fullscreen mode

Notice the availability zones input. AWS wants us-east-1a. Azure wants 1. Same variable, different values. The interface is identical. The values are cloud-native. That is the right level of abstraction: common shape, native details.

When to share code vs when to diverge

The temptation is to abstract harder: one module, conditionals per cloud, a cloud variable that switches behavior. Resist it.

# Do not do this
resource "aws_vpc" "main" {
  count      = var.cloud == "aws" ? 1 : 0
  cidr_block = var.cidr_block
}

resource "azurerm_virtual_network" "main" {
  count               = var.cloud == "azure" ? 1 : 0
  name                = var.name
  address_space       = [var.cidr_block]
  resource_group_name = var.resource_group_name
  location            = var.location
}
Enter fullscreen mode Exit fullscreen mode

This looks DRY. It is not. It is one module with two implementations stapled together, and every change has to reason about both. The conditionals multiply. The variable list becomes the union of every cloud's requirements, most of them irrelevant for any given apply. Code review becomes an exercise in tracking which branch you are in.

The rule I use: abstract the interface, not the implementation. Shared inputs and outputs. Separate internals. Duplication of structure across three small modules is cheaper than one clever module with cloud conditionals.

Share code where clouds genuinely agree: naming conventions, tagging strategy, input validation, documentation patterns. Diverge where clouds differ: resource types, networking primitives, IAM models. The boundary between "genuinely agree" and "superficially similar" is where multi-cloud modules live or die.

Cloud-specific realities

Some differences you will hit in the first week:

Naming constraints. Azure storage accounts: lowercase, alphanumeric, 3-24 characters, globally unique. AWS S3 buckets: lowercase, hyphens allowed, 3-63 characters, globally unique. GCP buckets: similar to S3 but with its own edge cases. Write a naming module per cloud, or at minimum a validation block:

variable "storage_name" {
  type        = string
  description = "Storage account name (Azure: 3-24 chars, lowercase alphanumeric)"

  validation {
    condition     = can(regex("^[a-z0-9]{3,24}$", var.storage_name))
    error_message = "Azure storage account names must be 3-24 lowercase alphanumeric characters."
  }
}
Enter fullscreen mode Exit fullscreen mode

Tagging vs labels. AWS uses tags (key-value, up to 50 per resource). Azure uses tags (key-value, up to 50). GCP uses labels (lowercase, specific character rules, up to 64 per resource). Your tagging module needs per-cloud normalization. Do not pass AWS-style tags straight into GCP labels. They will fail validation in ways that are annoying to debug.

Networking primitives do not map 1:1. An AWS VPC with public and private subnets across AZs is not the same thing as an Azure VNet with subnets, and neither maps cleanly to a GCP VPC with its regional subnets. GCP subnets are regional. AWS subnets are zonal. Azure subnets live inside one VNet with no AZ affinity at the subnet level. Any abstraction that pretends these are identical is lying to you. The identical-inputs pattern handles this: the caller says "three zones," and each module translates that into its cloud's networking model.

IAM is the deepest divergence. AWS IAM (users, roles, policies, trust relationships), Azure RBAC (role definitions, assignments, scopes), GCP IAM (roles, bindings, conditions). There is no common abstraction here that survives contact with a real security review. Do IAM per cloud, natively, with per-cloud modules. Do not try to unify it.

CI/CD across clouds

Each cloud needs its own authentication in the pipeline, and the pipeline needs to keep them separated.

AWS: OIDC with GitHub Actions is the standard now. No long-lived keys.

# .github/workflows/terraform-aws.yml
permissions:
  id-token: write
  contents: read

jobs:
  apply:
    runs-on: ubuntu-latest
    steps:
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::111122223333:role/github-terraform
          aws-region: us-east-1
      - run: terraform init -backend-config="key=prod-aws.tfstate"
      - run: terraform apply -auto-approve plan.tfplan
Enter fullscreen mode Exit fullscreen mode

Azure: federated credentials on the service principal, same OIDC pattern.

# .github/workflows/terraform-azure.yml
permissions:
  id-token: write
  contents: read

jobs:
  apply:
    runs-on: ubuntu-latest
    steps:
      - uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
      - run: terraform init -backend-config="key=prod-azure.tfstate"
      - run: terraform apply -auto-approve plan.tfplan
Enter fullscreen mode Exit fullscreen mode

GCP: workload identity federation.

Separate workflows per cloud, not one mega-workflow with conditionals. Same reasoning as the modules: the orchestration shape is shared (plan on PR, apply on merge), the authentication is per cloud. If the Azure pipeline breaks, AWS deploys are unaffected.

Backend state follows the same split. One state file per cloud per environment per component. From Article 1's layout:

prod/
  aws/
    network/terraform.tfstate
    compute/terraform.tfstate
  azure/
    network/terraform.tfstate
    compute/terraform.tfstate
Enter fullscreen mode Exit fullscreen mode

Yes, this is a lot of state files. That is the cost of multi-cloud, stated plainly.

A realistic repo layout

infra/
  modules/
    network-aws/
    network-azure/
    network-gcp/
    compute-aws/
    compute-azure/
    tagging/          # shared: naming and tag normalization per cloud
  envs/
    prod-aws/
      main.tf         # composes modules, sets AWS values
      variables.tf
      backend.tf
    prod-azure/
      main.tf         # composes modules, sets Azure values
      variables.tf
      backend.tf
    prod-gcp/
      main.tf
      variables.tf
      backend.tf
  bootstrap/
    aws/              # state backend per account (Article 1)
    azure/
    gcp/
.github/
  workflows/
    terraform-aws.yml
    terraform-azure.yml
    terraform-gcp.yml
Enter fullscreen mode Exit fullscreen mode

Each envs/ directory is independently deployable. Each has its own state, its own pipeline, its own blast radius. A bad apply in prod-azure cannot touch prod-aws. That isolation is the entire point of the layout.

The operational reality check

Here is what multi-cloud actually costs, beyond the code:

  • State files multiply. Three clouds times N components times M environments. Each one needs a backend, locking, IAM, and someone who knows it exists.
  • Pipelines multiply. Per-cloud auth, per-cloud apply jobs, per-cloud failure modes. Your CI minutes go up. Your pipeline debugging surface triples.
  • Cognitive load multiplies. Your team now needs working knowledge of three clouds' networking, IAM, and quirks. Hiring gets harder. Onboarding takes longer. The person who knows all three becomes a single point of failure.
  • Drift detection triples. Three clouds to scan, three sets of out-of-band changes to catch.
  • Cost visibility fragments. Each cloud has its own billing, its own cost explorer, its own tagging requirements. Unified cost views need additional tooling.

None of this is an argument against multi-cloud. It is an argument for doing it for a real reason. Residency requirements, contractual obligations, genuine resilience needs: these justify the cost. "Optionality" and resume-driven architecture do not.

Start with one cloud done well. Articles 1 through 6 of this series are about doing one cloud well: state, modules, CI/CD, drift, secrets. Add the second cloud when a requirement forces it, using the patterns above. Add the third when the second one taught you what you got wrong.

Series closing

Seven articles, one arc:

  1. Remote state. The foundation everything stands on. Backends, bootstrapping, locking, blast radius.
  2. Reusable modules. API gateways as the example, versioned registries, composition that survives team growth.
  3. CI/CD. Plan on PR, apply on merge, per-environment pipelines with OIDC.
  4. Drift detection. Finding the gap between state and reality, and closing it without drama.
  5. Workspaces vs directories. Environment strategy, and why directories win at scale.
  6. Vault integration. Secrets belong in Vault, state is still a secrets surface, dynamic credentials over static ones.
  7. Multi-cloud. One codebase, three clouds, and the honesty to ask whether you need it.

The thread running through all seven: Terraform rewards boring discipline. Remote state, small modules, locked applies, secrets in the right place. None of it is exciting. All of it is what separates infrastructure that survives from infrastructure that pages you at 3 AM.

Thanks for reading the series. If you are starting the HashiCorp Ambassador track, or just trying to run Terraform like you mean it, I hope something in here saved you an afternoon.

Top comments (0)