Module Structure and Interface

## Encapsulation is the point Terraform's module system gives a child module exactly two openings: `variable` blocks for values coming in, and `output` blocks for values going out. From outside, the only expression form that resolves is: ``` module.<module_name>.<output_name> ``` There is no `module.network.aws_subnet.private[0].id`. It is not that Terraform cannot see the resource — it can, it is right there in the plan and in state as `module.network.aws_subnet.private[0]` — it is that the *configuration language* refuses to let you depend on it. Encapsulation is enforced, not advised. That is a deliberate design. If callers could reach any resource inside a module, then every resource, every attribute and every `for_each` key would be part of the module's public surface, and no author could ever refactor. With outputs, the author decides what is promised. ```hcl # modules/network/outputs.tf output "private_subnet_ids" { description = "IDs of the private subnets, one per availability zone" value = [for s in aws_subnet.private : s.id] } ``` ```hcl # root resource "aws_db_subnet_group" "this" { name = "app" subnet_ids = module.network.private_subnet_ids } ``` ## The workarounds, and why each is worse When the output is missing, people reach for one of these: **Hard-code the value.** Paste the subnet ID as a literal string. It works until the subnet is replaced, and it silently makes the configuration environment-specific — the same code will point at production's subnet from staging. **Add a data source in the root.** Look the subnet back up by tag or name filter. Now there is a hidden coupling to the module's tagging scheme, and a dependency Terraform cannot order correctly: the data source may read before the resource exists on the first apply, or return a stale value. **Read it out of state.** Parse `terraform show -json`, or point a `terraform_remote_state` data source at the state and dig into the module's internal resources. This makes the internal layout of another team's module into a contract they never agreed to, and it breaks the moment they rename a resource. **Fork the module.** The heaviest cost of all, for one missing line. The correct fix is a one-line pull request against the module. Adding an output is *additive*: no existing caller changes behaviour, no plan diff appears for anyone. This is the cheapest kind of interface change there is, and a module maintainer should accept them readily. ## Outputs propagate one level at a time Encapsulation applies at every level, so a value from a grandchild module is not automatically visible to the grandparent. If `modules/platform` calls `modules/network`, and the root calls `modules/platform`, then to expose the VPC ID the root must see, `platform` has to re-export it: ```hcl # modules/platform/outputs.tf output "vpc_id" { value = module.network.vpc_id } ``` This pass-through plumbing is real work at each layer and is one of the concrete costs of a deep module tree. ## Designing the output surface A few rules of thumb separate a module that ages well from one that becomes a liability: - **Export stable identities, not implementation shapes.** `vpc_id`, `cluster_endpoint`, `role_arn`, `security_group_id`. These are the values other configuration genuinely needs. - **Be careful exporting whole objects.** `output "bucket" { value = aws_s3_bucket.this }` is convenient and then permanent: every attribute of that resource becomes something a caller may be relying on, and you will not know which. - **Give every output a `description`.** It is what documentation generators publish and what a consumer reads first. - **Name for meaning, not for the resource.** `private_subnet_ids` survives a refactor from `aws_subnet` to a different construction; `aws_subnet_private_ids` advertises the implementation. - **Prefer plural collections with predictable shapes.** A map keyed by a meaningful key (availability zone, environment name) is far easier for a caller to consume than a list whose order depends on internal iteration. ## Changing an existing output Adding is safe; the other three operations are not. Removing an output breaks any caller referencing it, with an immediate configuration error — loud, but breaking. Renaming is removal plus addition. The dangerous one is *changing the meaning or type* of an existing output — switching a list to a map, or making `subnet_ids` return public subnets where it used to return private ones. That produces no error at all, just a plan that quietly rewires production. Treat the set of outputs, their names, their types and their semantics as the thing consumers depend on, because it is.