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
Syntax
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’svariableandoutputblocks.- A caller that sets the variable, or reads the output, gets a warning with the message.
See Marking variable as deprecated and Marking output as deprecated in the OpenTofu docs.
Prerequisites
- OpenTofu installed. Installing OpenTofu in the OpenTofu docs covers every system.
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.tf
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.tf
module "shop" {
source = "./modules/shop"
title = "Riverside Bookshop"
}
output "shop" {
value = module.shop.name
}
Terminal
tofu init
tofu plan
Output
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.tf
module "shop" {
source = "./modules/shop"
shop_name = "Riverside Bookshop"
}
output "shop" {
value = module.shop.heading
}
Terminal
tofu plan
Output (the lines that matter)
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:
Terminal
tofu plan -deprecation=module:none
Clean Up
Nothing was created. Delete the folder.
Common Mistakes
| Mistake | What happens | Do this instead |
|---|---|---|
| Removing the old variable straight away | Every caller that still sets it gets an error. | Deprecate it first, and remove it in a later major version. |
| Writing a vague message | Callers 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.
Related
- OpenTofu Tutorial — Part 4: Variables, tfvars and Outputs
- How to Use Input Variables in OpenTofu
- How to Use Output Values in OpenTofu
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.
