Importance of 'lineage' in Terraform state file


Can anyone please explain the importance of ‘lineage’ in Terraform state file?. Terraform documentation says "The “lineage” is a unique ID assigned to a state when it is created. ". When I change resource type etc, I see ‘serial’ value being increased but not ‘lineage’.

When does ‘lineage’ value change? I didn’t face a scenario yet where ‘lineage’ value changes, so just curious.

Thanks in advance.

Hi @coolbreeze,

For a particular state the lineage should never change: its purpose is to recognize the difference between a new snapshot of the same state (same lineage, new serial) vs a snapshot of an unrelated state (different lineage, regardless of serial).

In practice that property isn’t as important as it was in older Terraform versions. In Terraform 0.8 and earlier users always needed to specify the state storage location on the command line before running Terraform, and so this mechanism served to catch mistakes where someone might accidentally ask Terraform to overwrite the production environment’s state with the latest snapshot from the staging environment.

In modern Terraform there are fewer opportunities for that, because in most cases we specify the state storage settings using configuration in the root module and use separate root modules for each environment. It can still be useful in some less common situations, though:

  • When running terraform init it’s possible to override backend config settings and instruct Terraform to migrate state snapshots to a new location. If you specify a location which already has an unrelated state snapshot present, Terraform will check the lineage and refuse to overwrite it.
  • If using terraform state pull and terraform state push to migrate manually or backup/restore state snapshots, the push command will check to make sure it isn’t overwriting a snapshot of some other state, unless you use -force.

Thanks, @apparentlymart. Sorry for the delayed response. Thanks for explaining in detail about ‘lineage’ attribute.