github.com/hugorut/terraform@v1.1.3/website/docs/language/functions/nonsensitive.mdx (about)

     1  ---
     2  page_title: nonsensitive - Functions - Configuration Language
     3  description: >-
     4    The nonsensitive function removes the sensitive marking from a value that
     5    Terraform considers to be sensitive.
     6  ---
     7  
     8  # `nonsensitive` Function
     9  
    10  -> **Note:** This function is only available in Terraform v0.15 and later.
    11  
    12  `nonsensitive` takes a sensitive value and returns a copy of that value with
    13  the sensitive marking removed, thereby exposing the sensitive value.
    14  
    15  ~> **Warning:** Using this function indiscriminately will cause values that
    16  Terraform would normally have considered as sensitive to be treated as normal
    17  values and shown clearly in Terraform's output. Use this function only when
    18  you've derived a new value from a sensitive value in a way that eliminates the
    19  sensitive portions of the value.
    20  
    21  Normally Terraform tracks when you use expressions to derive a new value from
    22  a value that is marked as sensitive, so that the result can also be marked
    23  as sensitive.
    24  
    25  However, you may wish to write expressions that derive non-sensitive results
    26  from sensitive values. For example, if you know based on details of your
    27  particular system and its threat model that a SHA256 hash of a particular
    28  sensitive value is safe to include clearly in Terraform output, you could use
    29  the `nonsensitive` function to indicate that, overriding Terraform's normal
    30  conservative behavior:
    31  
    32  ```hcl
    33  output "sensitive_example_hash" {
    34    value = nonsensitive(sha256(var.sensitive_example))
    35  }
    36  ```
    37  
    38  Another example might be if the original value is only partially sensitive and
    39  you've written expressions to separate the sensitive and non-sensitive parts:
    40  
    41  ```hcl
    42  variable "mixed_content_json" {
    43    description = "A JSON string containing a mixture of sensitive and non-sensitive values."
    44    type        = string
    45    sensitive   = true
    46  }
    47  
    48  locals {
    49    # mixed_content is derived from var.mixed_content_json, so it
    50    # is also considered to be sensitive.
    51    mixed_content = jsondecode(var.mixed_content_json)
    52  
    53    # password_from_json is derived from mixed_content, so it's
    54    # also considered to be sensitive.
    55    password_from_json = local.mixed_content["password"]
    56  
    57    # username_from_json would normally be considered to be
    58    # sensitive too, but system-specific knowledge tells us
    59    # that the username is a non-sensitive fragment of the
    60    # original document, and so we can override Terraform's
    61    # determination.
    62    username_from_json = nonsensitive(local.mixed_content["username"])
    63  }
    64  ```
    65  
    66  When you use this function, it's your responsibility to ensure that the
    67  expression passed as its argument will remove all sensitive content from
    68  the sensitive value it depends on. By passing a value to `nonsensitive` you are
    69  declaring to Terraform that you have done all that is necessary to ensure that
    70  the resulting value has no sensitive content, even though it was derived
    71  from sensitive content. If a sensitive value appears in Terraform's output
    72  due to an inappropriate call to `nonsensitive` in your module, that's a bug in
    73  your module and not a bug in Terraform itself.
    74  **Use this function sparingly and only with due care.**
    75  
    76  `nonsensitive` will return an error if you pass a value that isn't marked
    77  as sensitive, because such a call would be redundant and potentially confusing
    78  or misleading to a future maintainer of your module. Use `nonsensitive` only
    79  after careful consideration and with definite intent.
    80  
    81  Consider including a comment adjacent to your call to explain to future
    82  maintainers what makes the usage safe and thus what invariants they must take
    83  care to preserve under future modifications.
    84  
    85  ## Examples
    86  
    87  The following examples are from `terraform console` when running in the
    88  context of the example above with `variable "mixed_content_json"` and
    89  the local value `mixed_content`, with a valid JSON string assigned to
    90  `var.mixed_content_json`.
    91  
    92  ```
    93  > var.mixed_content_json
    94  (sensitive)
    95  > local.mixed_content
    96  (sensitive)
    97  > local.mixed_content["password"]
    98  (sensitive)
    99  > nonsensitive(local.mixed_content["username"])
   100  "zqb"
   101  > nonsensitive("clear")
   102  
   103  Error: Invalid function argument
   104  
   105  Invalid value for "value" parameter: the given value is not sensitive, so this
   106  call is redundant.
   107  ```
   108  
   109  Note though that it's always your responsibility to use `nonsensitive` only
   110  when it's safe to do so. If you use `nonsensitive` with content that
   111  _ought to be_ considered sensitive then that content will be disclosed:
   112  
   113  ```
   114  > nonsensitive(var.mixed_content_json)
   115  <<EOT
   116  {
   117    "username": "zqb",
   118    "password": "p4ssw0rd"
   119  }
   120  EOT
   121  > nonsensitive(local.mixed_content)
   122  {
   123    "password" = "p4ssw0rd"
   124    "username" = "zqb"
   125  }
   126  > nonsensitive(local.mixed_content["password"])
   127  "p4ssw0rd"
   128  ```