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
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 (opens in a new tab) and Marking output as deprecated (opens in a new tab) in the OpenTofu docs.
Prerequisites
- OpenTofu installed. Installing OpenTofu (opens in a new tab) 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:
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:
module "shop" {
source = "./modules/shop"
title = "Riverside Bookshop"
}
output "shop" {
value = module.shop.name
}
tofu init
tofu plan
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
module "shop" {
source = "./modules/shop"
shop_name = "Riverside Bookshop"
}
output "shop" {
value = module.shop.heading
}
tofu plan
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:
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
- Marking variable as deprecated (opens in a new tab)
- Marking output as deprecated (opens in a new tab)
- Command: plan, other options (opens in a new tab)
- Modules (opens in a new tab)
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