From d7f3239c51ac43e31a433148ad7c3e5514c866be Mon Sep 17 00:00:00 2001
From: Pam Selle <204372+pselle@users.noreply.github.com>
Date: Mon, 14 Dec 2020 15:38:47 -0500
Subject: [PATCH] Document sensitivity + function call behavior

---
 .../expressions/function-calls.html.md        | 20 +++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/website/docs/configuration/expressions/function-calls.html.md b/website/docs/configuration/expressions/function-calls.html.md
index d65c0b3f1..b0deb2b99 100644
--- a/website/docs/configuration/expressions/function-calls.html.md
+++ b/website/docs/configuration/expressions/function-calls.html.md
@@ -48,6 +48,26 @@ min([55, 2453, 2]...)
 The expansion symbol is three periods (`...`), not a Unicode ellipsis character
 (`…`). Expansion is a special syntax that is only available in function calls.
 
+## Using Sensitive Data as Function Arguments
+
+When using sensitive data, such as [an input variable](https://www.terraform.io/docs/configuration/variables.html#suppressing-values-in-cli-output)
+or [an output defined](https://www.terraform.io/docs/configuration/outputs.html#sensitive-suppressing-values-in-cli-output) as sensitive
+as function arguments, the result of the function call will be marked as sensitive.
+
+This is a conservative behavior that is true irrespective of the function being
+called. For example, passing an object containing a sensitive input variable to
+the `keys()` function will result in a list that is sensitive:
+
+```shell
+> local.baz
+{
+  "a" = (sensitive)
+  "b" = "dog"
+}
+> keys(local.baz)
+(sensitive)
+```
+
 ## When Terraform Calls Functions
 
 Most of Terraform's built-in functions are, in programming language terms,