New rule: terraform_variable_nullable

[bendrucker]

Summary

Introduce a new terraform_variable_nullable rule that requires users to set nullable for variables with a default. This rule would be disabled by default. Eventually rules like terraform_documented_variables should be renamed to clearly group with this and other similar rules (e.g., terraform_variable_description).

Example

The following configuration is invalid and will error when called:

# main.tf
variable "foo" {
  default = "bar"
}

locals {
  templated = "foo=${var.foo}"
}

# terraform.auto.tfvars
foo = null

Output:

╷
│ Error: Invalid template interpolation value
│
│   on main.tf line 6, in locals:
│    6:   templated = "foo=${var.foo}"
│     ├────────────────
│     │ var.foo is null
│
│ The expression result is null. Cannot include a null value in a string
│ template.
╵

Cases

Invalid

Would emit a warning telling the user to set nullable:

variable "name" {
  type    = string
  default = "fred"
}

We can potentially suggest nullable = false as appropriate for most cases, but only the author can determine whether null is handled by the module. Terraform has many options for this, including val == null and functions like coalesce. It may be theoretically possible to detect null handling with static analysis, but it's impractically difficult.

Valid

No warning, because the module should be handling null as its the default:

variable "custom_setting" {
  type    = string
  default = null 
}

Ignored as not applicable:

variable "required_thing" {
  type = string
}

Background

Since Terraform 0.12, setting an attribute to null has been equivalent to leaving it unset.

https://www.hashicorp.com/blog/terraform-0-12-conditional-operator-improvements

At the time, this behavior only applied to provider attributes, and not module attributes. A module might define this:

variable "name" {
  type    = string
  default = "my-thing"
}

Ideally, a caller should be able to do this:

variable "name" {
  type    = string
  default = null
}

module "m" {
  name = var.name
}

If the calling module specifies a name, it should override the default. Otherwise, the default should be used. From 0.12 through 1.0, this wasn't possible.

Terraform 1.1 introduced nullable, which enables this behavior:

https://developer.hashicorp.com/terraform/language/values/variables#disallowing-null-input-values

The child module would define:

variable "name" {
  type     = string
  default  = "my-thing"
  nullable = false
}

Setting nullable to false ensures that the variable value will never be null within the module. If nullable is false and the variable has a default value, then Terraform uses the default when a module input argument is null.

While the documentation does not explicitly explain this, this was introduced for backward compatibility, since enabling this behavior by default would be a breaking change:

https://discuss.hashicorp.com/t/request-for-feedback-optional-object-type-attributes-with-defaults-in-v1-3-alpha/40550/27

There is not a mechanism exactly equivalent to “nullable”, because nullable was a compromise we were forced to take in order to remain backward-compatible with modules written before it existed.

Specifically, there is one case that has no equivalent in optional attributes: distinguishing between a caller explicitly assigning null and a caller just omitting an optional argument entirely. We consider it a historical design error that it was possible to distinguish those cases; assigning a null value to an optional input variable that specified a default should’ve caused the final value to be that default. nullable = false effectively opts in to that correct behavior, and disables the incorrectly-designed behavior.

Also: hashicorp/terraform#29832

In a future language edition where we make nullable=false the default...

In most cases, variables with defined defaults should set nullable = false. However, there are valid cases for nullable = true if the module handles null values for that variable.

[jta]

Would emit a warning telling the user to set nullable = true:

This feels a bit pedantic given validation would immediately fail for the case where nullable = false:

│ Error: Invalid default value for variable
│
│   on variables.tf line 3, in variable "custom_setting":
│    3:   default  = null
│
│ A null default value is not valid when nullable=false.

[bendrucker]

Yeah I guess that's not necessary, if default = null, the module needs to handle null. Removed.