Skip to main content
0 reactions

How to Deprecate Variables and Outputs in OpenTofu

Card titled Deprecate Variables and Outputs, showing a warning sign above the notes deprecated equals Use shop_name instead and Warning: marked as deprecated.
How to Deprecate Variables and Outputs in OpenTofu.

When you rename or remove a variable or an output of an OpenTofu® module, every configuration that uses it breaks. The deprecated argument gives the module’s users a warning first, while the old name still works.

This guide deprecates a variable and an output in a small module, shows the warnings a caller gets, and moves the caller to the new names.

Syntax

SyntaxHCL
variable "<NAME>" {
  deprecated = "<MESSAGE>"
}

output "<NAME>" {
  value      = <EXPRESSION>
  deprecated = "<MESSAGE>"
}
  • deprecated: a message, which must not be empty, that tells users what to use instead. It goes in a module’s variable and output blocks.
  • A caller that sets the variable, or reads the output, gets a warning with the message.

See Marking variable as deprecated (opens in a new tab) and Marking output as deprecated (opens in a new tab) in the OpenTofu docs.

Prerequisites

Step 1: Write a Module with Old and New Names

A module is a folder of configuration that another configuration calls. In an empty folder, create modules/shop/main.tf. The module once used title and name; now it uses shop_name and heading:

modules/shop/main.tfHCL
variable "title" {
  type       = string
  default    = null
  deprecated = "Use shop_name instead. The title variable will be removed in version 2."
}

variable "shop_name" {
  type    = string
  default = "Bookshop"
}

output "name" {
  value      = coalesce(var.title, var.shop_name)
  deprecated = "Use the heading output instead."
}

output "heading" {
  value = "Welcome to the ${coalesce(var.title, var.shop_name)}"
}

coalesce returns the first value that isn’t empty, so callers who still set title get the same result as before.

Step 2: Call It with the Old Names

Create main.tf in the top folder:

main.tfHCL
module "shop" {
  source = "./modules/shop"
  title  = "Riverside Bookshop"
}

output "shop" {
  value = module.shop.name
}
TerminalBash
tofu init
tofu plan
OutputPlain text
Changes to Outputs:
  + shop = "Riverside Bookshop"

You can apply this plan to save these new output values to the OpenTofu state, without
changing any real infrastructure.
╷
│ Warning: Variable marked as deprecated by the module author
│ 
│   on main.tf line 3, in module "shop":
│    3:   title  = "Riverside Bookshop"
│ 
│ Variable "title" is marked as deprecated with the following message:
│ Use shop_name instead. The title variable will be removed in version 2.
╵
╷
│ Warning: Value derived from a deprecated source
│ 
│   on main.tf line 7, in output "shop":
│    7:   value = module.shop.name
│ 
│ This value is derived from module.shop.name, which is deprecated with the following
│ message:
│ 
│ Use the heading output instead.
╵

The plan still works, with the old values, and OpenTofu shows one warning for each old name, with the module author’s message.

Step 3: Move to the New Names

main.tfHCL
module "shop" {
  source    = "./modules/shop"
  shop_name = "Riverside Bookshop"
}

output "shop" {
  value = module.shop.heading
}
TerminalBash
tofu plan
Output (the lines that matter)Plain text
Changes to Outputs:
  + shop = "Welcome to the Riverside Bookshop"

No warnings. Once every caller has moved, the module can drop the old names in its next major version.

Hide the Warnings with -deprecation

When you can’t change a module you use yet, -deprecation=module:none drops these warnings, and module:local shows them only for modules in your own folders:

TerminalBash
tofu plan -deprecation=module:none

Clean Up

Nothing was created. Delete the folder.

Common Mistakes

MistakeWhat happensDo this instead
Removing the old variable straight awayEvery caller that still sets it gets an error.Deprecate it first, and remove it in a later major version.
Writing a vague messageCallers see the warning but don’t know what to change.Name the replacement, as in "Use shop_name instead."

FAQ

Which OpenTofu version added deprecated?

OpenTofu 1.10. Older versions don’t accept the argument.

Does deprecated change the value?

No. It only adds a warning; the variable and the output work as before.

Conclusion

Mark old variables and outputs with deprecated, keep them working while callers move, and say in the message what to use instead.

Additional Resources

OpenTofu® is a registered trademark of LF Projects, LLC. Other names mentioned are trademarks of their respective owners. JD Bots isn’t affiliated with or endorsed by the OpenTofu project.

0 comments