Most engineers assume merge combines everything cleanly.
It doesn’t.
The mechanism is simple. Terraform reads maps from left to right. When keys collide, the last value wins. That behavior turns merge into a precedence engine, not a blending tool.
This is why merge is used to layer configuration:
- Global defaults define the baseline
- Environment overrides adjust behavior
- Resource-specific values finalize the input
The outcome is clean, predictable infrastructure.
But there is a hidden risk.
merge is shallow. If two maps share the same top-level key, the entire nested structure is replaced. Inner values are not combined. They are deleted and rewritten.
This is where production issues begin.
A missing nested field will not throw an error. It will silently disappear.
The lesson is not about syntax. It is about control.
If you treat merge as a policy layer, your infrastructure stays consistent. If you treat it as a helper, you will eventually lose configuration without noticing.