Preconditions and Postconditions

[alisdair]

This PR introduces two new concepts to help document expectations and assumptions about resources, data sources, and outputs. By specifying precondition and postcondition blocks, module authors can define explicit checks which must be true for the configuration to be valid.

Preconditions are checked before creating a resource, reading a data source, or recording a module output value. These can be thought of as documented assumptions about the referenced data, which are checked by Terraform on every plan and apply. Preconditions can refer to values elsewhere in the configuration (which may cause Terraform to reorder the operations on those dependencies).

Postconditions are checked after creating a resource or reading a data source. As such, they may refer to values in the resource or data source directly. These can be thought of as assertions about the referenced data, ensuring that the module adheres to an explicit contract.

In configuration, preconditions and postconditions look a lot like custom variable validation rules, and in fact use the same underlying code. Here's a brief example:

resource "aws_instance" "example" {
  instance_type = "t2.micro"
  ami           = "ami-abc123"

  lifecycle {
    # A resource with a precondition can ensure that the selected AMI
    # is set up correctly to work with the instance configuration.
    precondition {
      condition     = data.aws_ami.example.architecture == "x86_64"
      error_message = "The selected AMI must be for the x86_64 architecture."
    }

    # A resource with a postcondition can react to server-decided values
    # during the apply step and halt work immediately if the result doesn't
    # meet expectations.
    postcondition {
      condition     = self.private_dns != ""
      error_message = "EC2 instance must be in a VPC that has private DNS hostnames enabled."
    }
  }
}

For more examples and further background, see the included documentation page.

This PR is a rebase and update of #27008, and as such most of the code was written by @apparentlymart, apart from the bugs which are probably mine.

[jbardin]

We also need to verify that there are no self-references via a full address in these blocks, as that will bypass the self check in preconditions and possibly cause cycles to crop up during apply. This otherwise LGTM if you want to tackle that extra validation in a separate PR.

[alisdair]

Thanks! Good catch, and I'll handle that in a follow-up PR for easier review.

[github-actions]

Reminder for the merging maintainer: if this is a user-visible change, please update the changelog on the appropriate release branch.

[github-actions]

I'm going to lock this pull request because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active contributions.
If you have found a problem that seems related to this change, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.