* website: v0.15 upgrade guide for sensitive resource attributes
Our earlier draft of this guide didn't include a section about the
stabilization of the "provider_sensitive_attrs" language experiment. This
new section aims to address the situation where a module might previously
have been returning a sensitive value without having marked it as such,
and thus that module will begin returning an error after upgrading to
Terraform v0.15.
As part of that, I also reviewed the existing documentation about these
features and made some edits aiming to make these four different sections
work well together if users refer to them all at once, as they are likely
to do if they follow the new links from the upgrade guide. I aimed to
retain all of the content we had before, but some of it is now in a new
location.
In particular, I moved the discussion about the v0.14 language experiment
into the upgrade guide, because it seems like a topic only really relevant
to those upgrading from an earlier version and not something folks need to
know about if they are using Terraform for the first time in v0.15 or
later.
* minor fixups
Co-authored-by: Kristin Laemmert <mildwonkey@users.noreply.github.com>
@ -277,6 +277,36 @@ Note that unlike `count`, splat expressions are _not_ directly applicable to res
* `values(aws_instance.example)[*].id`
### Sensitive Resource Attributes
When defining the schema for a resource type, a provider developer can mark
certain attributes as _sensitive_, in which case Terraform will show a
placeholder marker `(sensitive)` instead of the actual value when rendering
a plan involving that attribute.
A provider attribute marked as sensitive behaves similarly to an
[an input variable declared as sensitive](/docs/language/values/variables.html#suppressing-values-in-cli-output),
where Terraform will hide the value in the plan and apply messages and will
also hide any other values you derive from it as sensitive.
However, there are some limitations to that behavior as described in
[Cases where Terraform may disclose a sensitive variable](/docs/language/values/variables.html#cases-where-terraform-may-disclose-a-sensitive-variable).
If you use a sensitive value from a resource attribute as part of an
[output value](/docs/language/values/outputs.html) then Terraform will require
you to also mark the output value itself as sensitive, to confirm that you
intended to export it.
Terraform will still record sensitive values in the [state](/docs/language/state/index.html),
and so anyone who can access the state data will have access to the sensitive
values in cleartext. For more information, see
[_Sensitive Data in State_](/docs/language/state/sensitive-data.html).
-> **Note:** Treating values derived from a sensitive resource attribute as
sensitive themselves was introduced in Terraform v0.15. Earlier versions of
Terraform will obscure the direct value of a sensitive resource attribute,
but will _not_ automatically obscure other values derived from sensitive
resource attributes.
### Values Not Yet Known
When Terraform is planning a set of changes that will apply your configuration,
@ -317,44 +347,3 @@ effect:
until the apply phase, causing the apply to fail.
Unknown values appear in the `terraform plan` output as `(not yet known)`.
### Sensitive Resource Attributes
When defining the schema for a resource type, a provider developer can mark
certain attributes as _sensitive_, in which case Terraform will show a
placeholder marker `(sensitive)` instead of the actual value when rendering
a plan involving that attribute.
The treatment of these particular sensitive values is currently different than
Setting an output value as sensitive prevents Terraform from showing its value
in `plan` and `apply`. In the following scenario, our root module has an output declared as sensitive
and a module call with a sensitive output, which we then use in a resource attribute.
Terraform will hide values marked as sensitive in the messages from
`terraform plan` and `terraform apply`. In the following scenario, our root
module has an output declared as sensitive and a module call with a
sensitive output, which we then use in a resource attribute.
```hcl
# main.tf
@ -130,11 +131,9 @@ output "a" {
}
```
When we run a `plan` or `apply`, the sensitive value is redacted from output:
When we run a plan or apply, the sensitive value is redacted from output:
```
# CLI output
Terraform will perform the following actions:
# test_instance.x will be created
@ -148,11 +147,15 @@ Changes to Outputs:
+ out = (sensitive value)
```
-> **Note:** In Terraform versions prior to Terraform 0.14, setting an output value in the root module as sensitive would prevent Terraform from showing its value in the list of outputs at the end of `terraform apply`. However, the value could still display in the CLI output for other reasons, like if the value is referenced in an expression for a resource argument.
-> **Note:** In Terraform versions prior to Terraform 0.14, setting an output
value in the root module as sensitive would prevent Terraform from showing its
value in the list of outputs at the end of `terraform apply`. However, the
value could still display in the CLI output for other reasons, like if the
value is referenced in an expression for a resource argument.
Sensitive output values are still recorded in the
[state](/docs/language/state/index.html), and so will be visible to anyone who is able
to access the state data. For more information, see
Terraform will still record sensitive values in the [state](/docs/language/state/index.html),
and so anyone who can access the state data will have access to the sensitive
values in cleartext. For more information, see
[_Sensitive Data in State_](/docs/language/state/sensitive-data.html).
@ -211,13 +211,16 @@ using a sentence structure similar to the above examples.
> **Hands-on:** Try the [Protect Sensitive Input Variables](https://learn.hashicorp.com/tutorials/terraform/sensitive-variables?in=terraform/configuration-language&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn.
Setting a variable as `sensitive` prevents Terraform from showing its value in the `plan` or `apply` output, when that variable is used within a configuration.
Sensitive values are still recorded in the [state](/docs/language/state/index.html), and so will be visible to anyone who is able to access the state data. For more information, see [_Sensitive Data in State_](/docs/language/state/sensitive-data.html).
Setting a variable as `sensitive` prevents Terraform from showing its value in
the `plan` or `apply` output, when you use that variable elsewhere in your
configuration.
A provider can define [an attribute as sensitive](/docs/extend/best-practices/sensitive-state.html#using-the-sensitive-flag), which prevents the value of that attribute from being displayed in logs or regular output. The `sensitive` argument on variables allows users to replicate this behavior for values in their configuration, by defining a variable as `sensitive`.
Terraform will still record sensitive values in the [state](/docs/language/state/index.html),
and so anyone who can access the state data will have access to the sensitive
values in cleartext. For more information, see
[_Sensitive Data in State_](/docs/language/state/sensitive-data.html).
Define a variable as sensitive by setting the `sensitive` argument to `true`:
Declare a variable as sensitive by setting the `sensitive` argument to `true`:
```
variable "user_information" {
@ -234,7 +237,9 @@ resource "some_resource" "a" {
}
```
Using this variable throughout your configuration will obfuscate the value from display in `plan` or `apply` output:
Any expressions whose result depends on the sensitive variable will be treated
as sensitive themselves, and so in the above example the two arguments of
`resource "some_resource" "a"` will also be hidden in the plan output:
```
Terraform will perform the following actions:
@ -248,22 +253,12 @@ Terraform will perform the following actions:
Plan: 1 to add, 0 to change, 0 to destroy.
```
In some cases where a sensitive variable is used in a nested block, the whole block can be redacted. This happens with resources which can have multiple blocks of the same type, where the values must be unique. This looks like:
In some cases where you use a sensitive variable inside a nested block, Terraform
may treat the entire block as redacted. This happens for resource types where
all of the blocks of a particular type are required to be unique, and so
disclosing the content of one block might imply the content of a sibling block.
```
# main.tf
resource "some_resource" "a" {
nested_block {
user_information = var.user_information # a sensitive variable
other_information = "not sensitive data"
}
}
# CLI output
Terraform will perform the following actions:
# some_resource.a will be updated in-place
~ resource "some_resource" "a" {
~ nested_block {
@ -271,9 +266,19 @@ Terraform will perform the following actions:
# so its contents will not be displayed.
}
}
```
A provider can also
[declare an attribute as sensitive](/docs/extend/best-practices/sensitive-state.html#using-the-sensitive-flag),
which will cause Terraform to hide it from regular output regardless of how
[output value](/docs/language/values/outputs.html) then Terraform will require
you to also mark the output value itself as sensitive, to confirm that you
intended to export it.
#### Cases where Terraform may disclose a sensitive variable
A `sensitive` variable is a configuration-centered concept, and values are sent to providers without any obfuscation. A provider error could disclose a value if that value is included in the error message. For example, a provider might return the following error even if "foo" is a sensitive value: `"Invalid value 'foo' for field"`
Martin Atkins
5 years ago
committed by
GitHub