mirror of
https://github.com/opentffoundation/opentf.git
synced 2026-03-25 14:00:21 -04:00
89b2405080
These aim to allow hinting to Terraform about situations where it's not able to automatically infer value sensitivity. "nonsensitive" is for situations where Terraform's behavior is too conservative, such as when a new value is derived from a sensitive value in such a way that all of the sensitive content is removed. "sensitive", on the other hand, is for situations where Terraform can't otherwise infer that a value is sensitive. These situations should be pretty rare in a module that's making effective use of sensitive input variables and output values, but the documentation shows one example of an uncommon situation where a more direct hint via this function would be needed. Both of these functions are aimed at only occasional use in unusual situations. They are here for reasons of pragmatism, not because we expect them to be used routinely or recommend their use.
130 lines
4.6 KiB
Markdown
130 lines
4.6 KiB
Markdown
---
|
|
layout: "language"
|
|
page_title: "nonsensitive - Functions - Configuration Language"
|
|
sidebar_current: "docs-funcs-conversion-sensitive"
|
|
description: |-
|
|
The nonsensitive function removes the sensitive marking from a value that Terraform considers to be sensitive.
|
|
---
|
|
|
|
# `nonsensitive` Function
|
|
|
|
-> **Note:** This function is only available in Terraform v0.14 and later.
|
|
|
|
`nonsensitive` takes a sensitive value and returns a copy of that value with
|
|
the sensitive marking removed, thereby exposing the sensitive value.
|
|
|
|
~> **Warning:** Using this function indiscriminately will cause values that
|
|
Terraform would normally have considered as sensitive to be treated as normal
|
|
values and shown clearly in Terraform's output. Use this function only when
|
|
you've derived a new value from a sensitive value in a way that eliminates the
|
|
sensitive portions of the value.
|
|
|
|
Normally Terraform tracks when you use expressions to derive a new value from
|
|
a value that is marked as sensitive, so that the result can also be marked
|
|
as sensitive.
|
|
|
|
However, you may wish to write expressions that derive non-sensitive results
|
|
from sensitive values. For example, if you know based on details of your
|
|
particular system and its threat model that a SHA256 hash of a particular
|
|
sensitive value is safe to include clearly in Terraform output, you could use
|
|
the `nonsensitive` function to indicate that, overriding Terraform's normal
|
|
conservative behavior:
|
|
|
|
```hcl
|
|
output "sensitive_example_hash" {
|
|
value = nonsensitive(sha256(var.sensitive_example))
|
|
}
|
|
```
|
|
|
|
Another example might be if the original value is only partially sensitive and
|
|
you've written expressions to separate the sensitive and non-sensitive parts:
|
|
|
|
```hcl
|
|
variable "mixed_content_json" {
|
|
description = "A JSON string containing a mixture of sensitive and non-sensitive values."
|
|
type = string
|
|
sensitive = true
|
|
}
|
|
|
|
locals {
|
|
# mixed_content is derived from var.mixed_content_json, so it
|
|
# is also considered to be sensitive.
|
|
mixed_content = jsondecode(var.mixed_content_json)
|
|
|
|
# password_from_json is derived from mixed_content, so it's
|
|
# also considered to be sensitive.
|
|
password_from_json = local.mixed_content["password"]
|
|
|
|
# username_from_json would normally be considered to be
|
|
# sensitive too, but system-specific knowledge tells us
|
|
# that the username is a non-sensitive fragment of the
|
|
# original document, and so we can override Terraform's
|
|
# determination.
|
|
username_from_json = nonsensitive(local.mixed_content["username"])
|
|
}
|
|
```
|
|
|
|
When you use this function, it's your responsibility to ensure that the
|
|
expression passed as its argument will remove all sensitive content from
|
|
the sensitive value it depends on. By passing a value to `nonsensitive` you are
|
|
declaring to Terraform that you have done all that is necessary to ensure that
|
|
the resulting value has no sensitive content, even though it was derived
|
|
from sensitive content. If a sensitive value appears in Terraform's output
|
|
due to an inappropriate call to `nonsensitive` in your module, that's a bug in
|
|
your module and not a bug in Terraform itself.
|
|
**Use this function sparingly and only with due care.**
|
|
|
|
`nonsensitive` will return an error if you pass a value that isn't marked
|
|
as sensitive, because such a call would be redundant and potentially confusing
|
|
or misleading to a future maintainer of your module. Use `nonsensitive` only
|
|
after careful consideration and with definite intent.
|
|
|
|
Consider including a comment adjacent to your call to explain to future
|
|
maintainers what makes the usage safe and thus what invariants they must take
|
|
care to preserve under future modifications.
|
|
|
|
## Examples
|
|
|
|
The following examples are from `terraform console` when running in the
|
|
context of the example above with `variable "mixed_content_json"` and
|
|
the local value `mixed_content`, with a valid JSON string assigned to
|
|
`var.mixed_content_json`.
|
|
|
|
```
|
|
> var.mixed_content_json
|
|
(sensitive)
|
|
> local.mixed_content
|
|
(sensitive)
|
|
> local.mixed_content["password"]
|
|
(sensitive)
|
|
> nonsensitive(local.mixed_content["username"])
|
|
"zqb"
|
|
> nonsensitive("clear")
|
|
|
|
Error: Invalid function argument
|
|
|
|
Invalid value for "value" parameter: the given value is not sensitive, so this
|
|
call is redundant.
|
|
```
|
|
|
|
Note though that it's always your responsibility to use `nonsensitive` only
|
|
when it's safe to do so. If you use `nonsensitive` with content that
|
|
_ought to be_ considered sensitive then that content will be disclosed:
|
|
|
|
```
|
|
> nonsensitive(var.mixed_content_json)
|
|
<<EOT
|
|
{
|
|
"username": "zqb",
|
|
"password": "p4ssw0rd"
|
|
}
|
|
EOT
|
|
> nonsensitive(local.mixed_content)
|
|
{
|
|
"password" = "p4ssw0rd"
|
|
"username" = "zqb"
|
|
}
|
|
> nonsensitive(local.mixed_content["password"])
|
|
"p4ssw0rd"
|
|
```
|