From b57248533d16805d099fda8e329435f97fae65b7 Mon Sep 17 00:00:00 2001 From: Pam Selle <204372+pselle@users.noreply.github.com> Date: Wed, 30 Sep 2020 11:21:08 -0400 Subject: [PATCH 1/7] Re-organize variable page for sensitive argument addition --- website/docs/configuration/variables.html.md | 74 +++++++++++--------- 1 file changed, 40 insertions(+), 34 deletions(-) diff --git a/website/docs/configuration/variables.html.md b/website/docs/configuration/variables.html.md index 70de50b23..09dfef50e 100644 --- a/website/docs/configuration/variables.html.md +++ b/website/docs/configuration/variables.html.md @@ -76,24 +76,24 @@ assign a value to the variable from outside and to reference the variable's value from within the module. The name of a variable can be any valid [identifier](./syntax.html#identifiers) -_except_ the following: - -- `source` -- `version` -- `providers` -- `count` -- `for_each` -- `lifecycle` -- `depends_on` -- `locals` +_except_ the following: `source`, `version`, `providers`, `count`, `for_each`, `lifecycle`, `depends_on`, `locals`. These names are reserved for meta-arguments in [module configuration blocks](./modules.html), and cannot be declared as variable names. -The variable declaration can optionally include a `type` argument to -specify what value types are accepted for the variable, as described -in the following section. +## Arguments + +Terraform CLI defines the following optional arguments for variable declarations: + +- [`default`][inpage-default] - A default value which then makes the variable optional. +- [`type`][inpage-type] - This argument specifies what value types are accepted for the variable. +- [`description`][inpage-description] - This specifies the input variable's documentation. +- [`validation`][inpage-validation] - A block to define validation rules, usually in addition to type constraints. + +### Default values + +[inpage-default]: #default-values The variable declaration can also include a `default` argument. If present, the variable is considered to be _optional_ and the default value will be used @@ -101,26 +101,9 @@ if no value is set when calling the module or running Terraform. The `default` argument requires a literal value and cannot reference other objects in the configuration. -## Using Input Variable Values +### Type Constraints -Within the module that declared a variable, its value can be accessed from -within [expressions](./expressions.html) as `var.`, -where `` matches the label given in the declaration block: - --> **Note:** Input variables are _created_ by a `variable` block, but you -_reference_ them as attributes on an object named `var`. - -```hcl -resource "aws_instance" "example" { - instance_type = "t2.micro" - ami = var.image_id -} -``` - -The value assigned to a variable can only be accessed in expressions within -the module where it was declared. - -## Type Constraints +[inpage-type]: #type-constraints The `type` argument in a `variable` block allows you to restrict the [type of value](./expressions.html#types-and-values) that will be accepted as @@ -155,7 +138,9 @@ as detailed information about automatic conversion of complex types, see If both the `type` and `default` arguments are specified, the given default value must be convertible to the specified type. -## Input Variable Documentation +### Input Variable Documentation + +[inpage-description]: #input-variable-documentation Because the input variables of a module are part of its user interface, you can briefly describe the purpose of each variable using the optional @@ -174,7 +159,9 @@ might be included in documentation about the module, and so it should be written from the perspective of the user of the module rather than its maintainer. For commentary for module maintainers, use comments. -## Custom Validation Rules +### Custom Validation Rules + +[inpage-validation]: #custom-validation-rules -> This feature was introduced in Terraform CLI v0.13.0. @@ -220,6 +207,25 @@ that includes the sentences given in `error_message`. The error message string should be at least one full sentence explaining the constraint that failed, using a sentence structure similar to the above examples. +## Using Input Variable Values + +Within the module that declared a variable, its value can be accessed from +within [expressions](./expressions.html) as `var.`, +where `` matches the label given in the declaration block: + +-> **Note:** Input variables are _created_ by a `variable` block, but you +_reference_ them as attributes on an object named `var`. + +```hcl +resource "aws_instance" "example" { + instance_type = "t2.micro" + ami = var.image_id +} +``` + +The value assigned to a variable can only be accessed in expressions within +the module where it was declared. + ## Assigning Values to Root Module Variables When variables are declared in the root module of your configuration, they From e369fe0559fa1d6d76f1042b7735a14717c81bdc Mon Sep 17 00:00:00 2001 From: Pam Selle <204372+pselle@users.noreply.github.com> Date: Wed, 30 Sep 2020 11:53:53 -0400 Subject: [PATCH 2/7] Docs for sensitive variables --- website/docs/configuration/variables.html.md | 67 ++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/website/docs/configuration/variables.html.md b/website/docs/configuration/variables.html.md index 09dfef50e..50a46f5a9 100644 --- a/website/docs/configuration/variables.html.md +++ b/website/docs/configuration/variables.html.md @@ -90,6 +90,7 @@ Terraform CLI defines the following optional arguments for variable declarations - [`type`][inpage-type] - This argument specifies what value types are accepted for the variable. - [`description`][inpage-description] - This specifies the input variable's documentation. - [`validation`][inpage-validation] - A block to define validation rules, usually in addition to type constraints. +- [`sensitive`][inpage-sensitive] - A boolean value that can limit Terraform UI output when the variable is used in configuration, to avoid accidental disclosure in logs or other UI. ### Default values @@ -207,6 +208,72 @@ that includes the sentences given in `error_message`. The error message string should be at least one full sentence explaining the constraint that failed, using a sentence structure similar to the above examples. +### Sensitive + +[inpage-sensitive]: #sensitive + +-> This feature was introduced in Terraform CLI v0.14.0. + +The `sensitive` argument on a variable block is a boolean value that, when provided, limits the output of the Terraform `plan` or `apply` when that variable is used. 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`. + +Once you have defined a sensitive variable, using it throughout your configuration will obfuscate the value from display in output: + +``` +variable "user_information" { + type = object({ + name = string + address = string + }) + sensitive = true +} + +resource "some_resource" "a" { + name = var.user_information.name + address = var.user_information.address +} +``` + +Running `terraform apply`: + +``` +Terraform will perform the following actions: + + # some_resource.a will be created + + resource "some_resource" "a" { + + name = (sensitive) + + address = (sensitive) + } + +Plan: 1 to add, 0 to change, 0 to destroy. +``` + +#### Cases where Terraform may disclose a sensitive variable + +Variable values marked as sensitive will display in state. Much like provider-side sensitive values, designating a value as sensitive only limits its display in logs or output, not in state. + +Similarly, `sensitive` argument does not have an impact in other Terraform commands such as `console` or `show`. Those commands are meant to ex as this argument is intended to reduce exposure of data in, for example, external logs or aggregation. + +Defining sensitivity at the variable level is a configuration-centered concept, and values are sent to providers without any obfuscation; as such, a provider error could disclose a value depending on if the value is included in the error message. For example, if a provider returns an error with `"Invalid value 'foo' for field"`, the value will be displayed in output as a consequence of this error. + +If a resource attribute is used as, or part of, the provider-defined resource id, an `apply` will disclose the value. In the example below, the `prefix` attribute has been set to a sensitive variable, but then that value ("jae") is later disclosed as part of the resource id: + +``` + # random_pet.animal will be created + + resource "random_pet" "animal" { + + id = (known after apply) + + length = 2 + + prefix = (sensitive) + + separator = "-" + } + +Plan: 1 to add, 0 to change, 0 to destroy. + +... + +random_pet.animal: Creating... +random_pet.animal: Creation complete after 0s [id=jae-known-mongoose] +``` + ## Using Input Variable Values Within the module that declared a variable, its value can be accessed from From 5cf61448e7af91293b9e6fcbd58c350a18a5ac04 Mon Sep 17 00:00:00 2001 From: Pam Selle Date: Thu, 1 Oct 2020 12:58:43 -0400 Subject: [PATCH 3/7] Update website/docs/configuration/variables.html.md Co-authored-by: Kristin Laemmert --- website/docs/configuration/variables.html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/configuration/variables.html.md b/website/docs/configuration/variables.html.md index 50a46f5a9..c639fb801 100644 --- a/website/docs/configuration/variables.html.md +++ b/website/docs/configuration/variables.html.md @@ -253,7 +253,7 @@ Variable values marked as sensitive will display in state. Much like provider-si Similarly, `sensitive` argument does not have an impact in other Terraform commands such as `console` or `show`. Those commands are meant to ex as this argument is intended to reduce exposure of data in, for example, external logs or aggregation. -Defining sensitivity at the variable level is a configuration-centered concept, and values are sent to providers without any obfuscation; as such, a provider error could disclose a value depending on if the value is included in the error message. For example, if a provider returns an error with `"Invalid value 'foo' for field"`, the value will be displayed in output as a consequence of this error. +A ` sensitive` variable level 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"` If a resource attribute is used as, or part of, the provider-defined resource id, an `apply` will disclose the value. In the example below, the `prefix` attribute has been set to a sensitive variable, but then that value ("jae") is later disclosed as part of the resource id: From 09551de078a92a63938a535fbfd1b2c17711230a Mon Sep 17 00:00:00 2001 From: Pam Selle <204372+pselle@users.noreply.github.com> Date: Thu, 1 Oct 2020 13:09:52 -0400 Subject: [PATCH 4/7] Rewrite intro to section, rename section, move state info Move the information about state from the "caveats" to the main info section, using similar information to sensitive outputs. Updates the header of the section from similar inspiration. --- website/docs/configuration/variables.html.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/website/docs/configuration/variables.html.md b/website/docs/configuration/variables.html.md index c639fb801..d383190bf 100644 --- a/website/docs/configuration/variables.html.md +++ b/website/docs/configuration/variables.html.md @@ -208,13 +208,17 @@ that includes the sentences given in `error_message`. The error message string should be at least one full sentence explaining the constraint that failed, using a sentence structure similar to the above examples. -### Sensitive +### Suppressing Values in CLI Output -[inpage-sensitive]: #sensitive +[inpage-sensitive]: #suppressing-values-in-cli-output -> This feature was introduced in Terraform CLI v0.14.0. -The `sensitive` argument on a variable block is a boolean value that, when provided, limits the output of the Terraform `plan` or `apply` when that variable is used. 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`. +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/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/state/sensitive-data.html). + +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`. Once you have defined a sensitive variable, using it throughout your configuration will obfuscate the value from display in output: @@ -249,10 +253,6 @@ Plan: 1 to add, 0 to change, 0 to destroy. #### Cases where Terraform may disclose a sensitive variable -Variable values marked as sensitive will display in state. Much like provider-side sensitive values, designating a value as sensitive only limits its display in logs or output, not in state. - -Similarly, `sensitive` argument does not have an impact in other Terraform commands such as `console` or `show`. Those commands are meant to ex as this argument is intended to reduce exposure of data in, for example, external logs or aggregation. - A ` sensitive` variable level 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"` If a resource attribute is used as, or part of, the provider-defined resource id, an `apply` will disclose the value. In the example below, the `prefix` attribute has been set to a sensitive variable, but then that value ("jae") is later disclosed as part of the resource id: From be50089c7fc1da87dd483e53a931f3737fb7c9fc Mon Sep 17 00:00:00 2001 From: Pam Selle <204372+pselle@users.noreply.github.com> Date: Thu, 1 Oct 2020 13:12:25 -0400 Subject: [PATCH 5/7] Rephrase sensitive index description --- website/docs/configuration/variables.html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/configuration/variables.html.md b/website/docs/configuration/variables.html.md index d383190bf..a65806717 100644 --- a/website/docs/configuration/variables.html.md +++ b/website/docs/configuration/variables.html.md @@ -90,7 +90,7 @@ Terraform CLI defines the following optional arguments for variable declarations - [`type`][inpage-type] - This argument specifies what value types are accepted for the variable. - [`description`][inpage-description] - This specifies the input variable's documentation. - [`validation`][inpage-validation] - A block to define validation rules, usually in addition to type constraints. -- [`sensitive`][inpage-sensitive] - A boolean value that can limit Terraform UI output when the variable is used in configuration, to avoid accidental disclosure in logs or other UI. +- [`sensitive`][inpage-sensitive] - Limits Terraform UI output when the variable is used in configuration. ### Default values From 93d38ff2d2153197819747ba1273c0b05c9d4914 Mon Sep 17 00:00:00 2001 From: Pam Selle <204372+pselle@users.noreply.github.com> Date: Thu, 1 Oct 2020 13:16:15 -0400 Subject: [PATCH 6/7] Update intro to code blocks --- website/docs/configuration/variables.html.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/configuration/variables.html.md b/website/docs/configuration/variables.html.md index a65806717..0829ec460 100644 --- a/website/docs/configuration/variables.html.md +++ b/website/docs/configuration/variables.html.md @@ -220,7 +220,7 @@ Sensitive values are still recorded in the [state](/docs/state/index.html), and 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`. -Once you have defined a sensitive variable, using it throughout your configuration will obfuscate the value from display in output: +Define a variable as sensitive by setting the `sensitive` argument to `true`: ``` variable "user_information" { @@ -237,7 +237,7 @@ resource "some_resource" "a" { } ``` -Running `terraform apply`: +Using this variable throughout your configuration will obfuscate the value from display in `plan` or `apply` output: ``` Terraform will perform the following actions: From 3ddbb4b009705786f115b333112c4f220042c6b4 Mon Sep 17 00:00:00 2001 From: Pam Selle <204372+pselle@users.noreply.github.com> Date: Thu, 1 Oct 2020 13:19:14 -0400 Subject: [PATCH 7/7] Update provider caveat grammar --- website/docs/configuration/variables.html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/configuration/variables.html.md b/website/docs/configuration/variables.html.md index 0829ec460..c50ab4991 100644 --- a/website/docs/configuration/variables.html.md +++ b/website/docs/configuration/variables.html.md @@ -253,7 +253,7 @@ Plan: 1 to add, 0 to change, 0 to destroy. #### Cases where Terraform may disclose a sensitive variable -A ` sensitive` variable level 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"` +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"` If a resource attribute is used as, or part of, the provider-defined resource id, an `apply` will disclose the value. In the example below, the `prefix` attribute has been set to a sensitive variable, but then that value ("jae") is later disclosed as part of the resource id: