github.com/muratcelep/terraform@v1.1.0-beta2-not-internal-4/website/docs/language/functions/nonsensitive.html.md (about)

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