Deprecation Warning For Input/Output Variables

[jonbrouse]

As open sources modules become more popular and teams in organizations create Terraform modules that depend on the remote state of another team's module, there is a need to communicate the evolution of a module.

This request is proposing the addition of an optional deprication_warning parameter to the output and input variable configuration. The depreciation notification would display when a module references the deprecated output via remote state.

Terraform Configuration Files Example

For this example we will first view the outputs.tf file from v1.0.0 of an example module.

output "route53_zone_id" {
  value = "${aws_route53_zone.route53_zone.zone_id}"
}

Below is the outputs.tf file from v1.1.0 of our example module. The output variable route53_zone_id has been updated to primary_zone_id.

output "route53_zone_id" {
  value = "${aws_route53_zone.primary_zone.zone_id}"
  deprication_warning = "The route53_zone_id output variable has been deprecated. Please use primary_zone_id"
}

output "primary_zone_id" {
  value = "${aws_route53_zone.primary_zone.zone_id}"
}

Expected Behavior

When the apply is run in the root module that references the output, a depreciation warning would be displayed

Warning: The route53_zone_id output variable has been deprecated. Please use primary_zone_id

Another option would be to use deprication_replacement instead of deprication_warning. This would allow Terraform to have more control over the message.

output "route53_zone_id" {
  value = "${aws_route53_zone.primary_zone.zone_id}"
  deprication_replacement = "primary_zone_id"
}

Output of terraform apply

Warning: module.our_example: "route53_zone_id": [DEPRECATED] Use primary_zone_id instead

[apparentlymart]

Hi @jonbrouse! Thanks for sharing this use-case.

Being able to mark things as deprecated definitely seems like a good idea. For outputs in particular things are tricky though, because Terraform doesn't currently analyze their usage in a way that would permit the conditional warning you suggest here. That doesn't mean it's impossible, of course, but we'll need to think about the best way to achieve it within Terraform's internal architecture, and probably also to accept that the warning won't be displayed in some edge cases where the attribute is accessed dynamically.

Supporting this idea for variable blocks would be easier, I think, because we're already verifying statically that each of the arguments in a module block correspond to a variable block with suitable settings.

We generally lean towards shorter names for these built-in arguments inside variable and output blocks, so I'd lean towards naming the argument merely deprecated to keep things concise:

output "route53_zone_id" {
  value      = "${aws_route53_zone.primary_zone.zone_id}"
  deprecated = "Use primary_zone_id instead."
}

output "primary_zone_id" {
  value = "${aws_route53_zone.primary_zone.zone_id}"
}

With the new warning message style coming in the next major release, that might generate something like this:

Warning: Deprecated output value

  on example.tf line 21, in resource "aws_route53_record" "example":
  21:   zone_id = module.example.route53_zone_id

The output value route53_zone_id is deprecated. Use primary_zone_id instead.

The development branch for the next major release has some significant changes to the configuration loader already, so we'll need to hold on this for now at least until that work is completed and merged. We'll consider this some more for a subsequent release.

Thanks again for this suggestion!

[jonbrouse]

Hey @apparentlymart thanks for the reply. Y'all are doing awesome work!

[jasonmcintosh]

Assuming Hashicorp is considering adding support for deprecating parameters - are you looking to add it on variables as well? Be nice to support "module version 1.2.2 deprecates this variable, instead use X to be removed in 1.3" kinda thing :)

[slavaaaaaaaaaa]

I'm seeking this as well, more for general use than just outputs.

In my case, I'm deprecating an internal company module in favour of including its resources in another module. Procedures for this require state moves, so embedding such instructions in the to-be-deprecated module would be ideal.

[rodrigodiez]

I am also interested in this behaviour. As we evolve our infrastructure we have to change our modules. Being able to warn engineers about deprecations is a key feature to help them migrate their code base gradually

[oswalya]

I would also be interested in seeing this. Any update?

[TrueCyberAxe]

Any progress?

[ghostsquad]

Is this on the roadmap?

[bryantbiggs]

I hate to be the +1 guy but bumping for visibility and maybe Hashicorp's current thoughts on this enhancement 🙏🏽

[apparentlymart]

As far as I'm aware, there is not yet any clear design for how to reliably determine when referring to a particular output value in a calling module, and I believe solving that would be the main blocker for implementing something like this.

Using the names from the original writeup as a placeholder, module.example.route53_zone_id is a straightforward case that I think we could handle today, but for a module using for_each we may see module.example["foo"].route53_zone_id which requires a more detailed level of static analysis than Terraform has needed before.

It's also possible to use an entire module instance as a value and pass it around as an object, which would require even more sophisticated static analysis to resolve fully. For example:

module "example" {
  # ...
}

locals {
  intermediate = {
    for a, v in module.example : a => v if contains(["route53_zone_id", "domain_name", a])
  }
}

output "zone_id" {
  value = local.intermediate.route53_zone_id
}

If is of course debatable how many of these more complicated cases are important to handle, but deciding that will itself require research, and so will be a part of formulating a design for this.