Linking Terraform Stacks by Alias, Not by Path
Splitting infrastructure into many small Terraform stacks is easy to justify: smaller blast radius, faster plans, clearer ownership. What nobody tells you up front is that the split creates a new problem. The Kubernetes add-ons stack needs the cluster endpoint from the cluster stack. The cluster stack needs the VPC. The database stack needs the VPC too. Something has to wire these together.
The usual answer is terraform_remote_state with the bucket, key and workspace pasted into each consumer. It works, and it rots: the moment one stack moves, or you need a variant of an environment, you're grepping for paths in thirty places.
The infrastructure repository I worked on solved this with a pattern I'd happily reuse: dependencies are declared as aliases, resolved through a single shared template, and overridable per environment.
Step one: each stack lists what it needs, by alias
Every stack that consumes another has a tiny dependencies.json. This is the one for the stack that installs cluster add-ons with Helm:
{
"vpc": { "infra_rel_path": "networking/vpc" },
"eks": { "infra_rel_path": "kubernetes/eks_upgrade" },
"rds": { "infra_rel_path": "data/rds" }
}
The keys (vpc, eks, rds) are what the Terraform code uses. The values say where that stack's state lives relative to the backend. Nothing here mentions buckets, regions or workspaces.
Step two: one template, symlinked everywhere
The resolution logic isn't copied into each stack. There is a single file, templates/_linked/dependencies.tf, and every stack contains a symlink to it:
dependencies.tf -> ../../../templates/_linked/dependencies.tf
That file reads the stack's dependencies.json, then builds a terraform_remote_state data source for each entry:
locals {
environment_root_dependencies = fileexists("${module.vars.environment_variables_root_path}/dependencies.json") ? jsondecode(file("${module.vars.environment_variables_root_path}/dependencies.json")) : {}
module_dependencies = fileexists("dependencies.json") ? jsondecode(file("dependencies.json")) : {}
dependencies = {
for k, v in local.module_dependencies :
k => {
infra_rel_path = try(local.environment_root_dependencies[k].infra_rel_path, v.infra_rel_path)
workspace = try(local.environment_root_dependencies[k].workspace, lookup(v, "workspace", terraform.workspace))
exclude = try(local.environment_root_dependencies[k].exclude, lookup(v, "exclude", false))
}
}
}
data "terraform_remote_state" "dependencies" {
for_each = { for k, v in local.dependencies : k => v if v.exclude == false }
backend = "s3"
config = {
bucket = module.vars.is_dr ? data.terraform_remote_state.init.outputs.backend_replica.bucket_id : data.terraform_remote_state.init.outputs.backend.bucket_id
key = "tf-states/${each.value.workspace}/${each.value.infra_rel_path}/terraform.tfstate"
region = module.vars.is_dr ? data.terraform_remote_state.init.outputs.backend_replica.bucket_region : data.terraform_remote_state.init.outputs.backend.bucket_region
}
}
The bucket and region come from the bootstrap stack's outputs (covered in the previous post), so the template is identical for every stack and every environment, including disaster-recovery workspaces that read from the replica bucket.
Aliases are resolved in one shared template, and the environment file wins
A consumer then reads outputs by alias:
cluster_endpoint = data.terraform_remote_state.dependencies["eks"].outputs.eks.cluster_endpoint
cluster_ca_cert = data.terraform_remote_state.dependencies["eks"].outputs.eks.cluster_certificate_authority_data
Step three: environments can override the wiring
Notice environment_root_dependencies. Each environment folder may contain its own dependencies.json, and anything in it wins over the stack default. That gives you three useful moves without editing any module.
Swap a dependency. The repository holds two EKS stacks side by side: the original and an upgraded one built on a newer version of the community EKS module. Consumers only know the alias eks, so pointing that alias at kubernetes/eks_upgrade is all it takes to make a consumer (add-ons, ingress, service accounts) follow the new cluster definition, with no change to consumer code.
Skip an optional stack. In some environments the optional PostgreSQL and managed-Kafka stacks exist in the repository but aren't deployed. Marking them excluded in the environment's file removes the data source entirely:
{
"postgresql": { "infra_rel_path": "data/postgresql", "exclude": true },
"msk": { "infra_rel_path": "streaming/kafka/msk", "exclude": true },
"eks": { "infra_rel_path": "kubernetes/eks_upgrade" }
}
Read from another workspace. The optional workspace field lets a stack read state from a different workspace than its own. Without it, the default is the current one.
The cost of this pattern
It isn't free, and I think it's worth being honest about where it hurts.
Aliases decouple paths, not contracts. A consumer still depends on the exact shape of the producer's outputs. The add-ons stack shows the scar tissue: when it reads the load balancer controller's role ARN it falls back between two output shapes with try(...), which suggests the two EKS stacks don't expose it identically. That's the price of keeping two producers behind one alias, and it's a good reminder to treat stack outputs as an API and version them like one.
There's also a build-order dependency that Terraform can't see. Each environment keeps an ordered build.json listing stacks from network up to workloads, because terraform_remote_state only reads what already exists. If you apply the consumer first, you get an empty state and a confusing error. A lightweight check (or a plan-time guard) that the producer's state exists would make that failure friendlier.
Data flows up the graph, so apply order has to follow it
When I'd use it again
The pattern earns its keep when there are many stacks and few people. The alias file is easy to read in review, and "where does this value come from" has exactly one answer. It also shines for environment variants that aren't forks, because exclusions and swaps live in data rather than in copy-pasted modules. And it makes migrations calmer: keeping old and new implementations available behind one alias turns moving a cluster into a one-line decision per environment.
Wrapping up
Treat the connections between stacks as configuration with a schema, not as strings scattered through code. A twenty-line shared template turned cross-stack wiring into something you can read in one place and change per environment. The aliases don't remove the need to treat outputs as an API or to respect build order, but they make both visible.