From 90624ad22387d228911e6d17c6e3b5eace203451 Mon Sep 17 00:00:00 2001
From: Chris White <chris@prefect.io>
Date: Wed, 13 Feb 2019 12:34:52 -0800
Subject: [PATCH 1/3] Add concept doc for secrets

---
 docs/.vuepress/config.js       |  3 +-
 docs/cloud_concepts/secrets.md | 72 ++++++++++++++++++++++++++++++++++
 2 files changed, 74 insertions(+), 1 deletion(-)
 create mode 100644 docs/cloud_concepts/secrets.md

diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
index 95658425ff3a..51eefafd8a86 100644
--- a/docs/.vuepress/config.js
+++ b/docs/.vuepress/config.js
@@ -124,7 +124,8 @@ module.exports = {
             'cloud_concepts/projects',
             'cloud_concepts/flows',
             'cloud_concepts/schedules',
-            'cloud_concepts/flow_runs'
+            'cloud_concepts/flow_runs',
+            'cloud_concepts/secrets'
           ]
         },
         {
diff --git a/docs/cloud_concepts/secrets.md b/docs/cloud_concepts/secrets.md
new file mode 100644
index 000000000000..0a2bad99b812
--- /dev/null
+++ b/docs/cloud_concepts/secrets.md
@@ -0,0 +1,72 @@
+# Secrets
+
+Secrets represent sensitive key / value pairs that might be required during execution of your Flow.  As an example,
+the [ability to receive slack notifications from Prefect](../tutorials/slack-notifications.html#using-your-url-to-get-notifications) relies on a secret
+URL.  It is easy to imagine other examples of Secrets that might be relevant, such as API credentials.
+
+## Setting a Secret
+As with everything in Prefect, there are two standard modes of operation: "local execution", intended mainly for testing or running non-production Flows, and "cloud execution" which utilizes the full Prefect backend.  
+
+### Locally
+During local execution, Secrets can easily be set and retrieved from your configuration file.  First, in your user configuration file set the `use_local_secrets` flag in the `[cloud]` section to `true`:
+```
+[cloud]
+use_local_secrets = true
+```
+This is also the default setting, so you only need to change this if you've changed it yourself.
+
+Now, to populate your local secrets you can simply add an additional section to your user config:
+```
+[context.secrets]
+KEY = VALUE
+```
+with however many key / value pairs you'd like.  
+
+::: tip You don't have to store raw values in your config
+Prefect will interpolate certain values from your OS environment, so you can specify values from environment variables via `"$ENV_VAR"`.
+:::
+
+### In Cloud
+
+To set a secret in Prefect Cloud, simply issue the following simple GraphQL mutation:
+```graphql
+mutation{
+  setSecret(input: {name: "KEY", value: "VALUE"}){
+    success
+  }
+}
+```
+
+## Using a Secret
+
+Secrets can be used anywhere, at any time.  This includes, but is not limited to:
+- Tasks
+- state handlers
+- callbacks
+- result handlers
+
+Creating a Secret and pulling its value is as simple as:
+```python
+from prefect.client import Secret
+
+s = Secret("NAME")
+s.get() # returns the value
+```
+
+Note that `s.get()` will not work locally unless `use_local_secrets` is set to `true` in your config.  To pull a Secret value from Cloud requires admin-level permissions.
+
+## Querying for Secrets
+
+Viewing all secrets by name:
+
+```graphql
+query {
+  secret(order_by: { name: asc }) {
+    name
+  }
+}
+```
+
+::: warning Secrets are secret
+You cannot query for the value of a Secret after it has been set.  These values are only available during Cloud execution.
+:::

From 83897c5a3b1563eebb8e26988e65e5a4a931e1f3 Mon Sep 17 00:00:00 2001
From: Chris White <chris@prefect.io>
Date: Thu, 14 Feb 2019 09:17:30 -0800
Subject: [PATCH 2/3] Add comment about overwriting secrets per feedback

---
 docs/cloud_concepts/secrets.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/cloud_concepts/secrets.md b/docs/cloud_concepts/secrets.md
index 0a2bad99b812..ee77faa1dd4d 100644
--- a/docs/cloud_concepts/secrets.md
+++ b/docs/cloud_concepts/secrets.md
@@ -37,6 +37,10 @@ mutation{
 }
 ```
 
+::: tip You can overwrite Secrets
+Changing the value of a Secret is as simple as re-issuing the above mutation with the new value.
+:::
+
 ## Using a Secret
 
 Secrets can be used anywhere, at any time.  This includes, but is not limited to:

From d82162db6a52c1294e3370bb46a540a072884cdf Mon Sep 17 00:00:00 2001
From: Chris White <chris@prefect.io>
Date: Fri, 15 Feb 2019 09:14:11 -0800
Subject: [PATCH 3/3] Secrets are _not_ available by admins either

---
 docs/cloud_concepts/secrets.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/cloud_concepts/secrets.md b/docs/cloud_concepts/secrets.md
index ee77faa1dd4d..1af784f97f6c 100644
--- a/docs/cloud_concepts/secrets.md
+++ b/docs/cloud_concepts/secrets.md
@@ -57,7 +57,7 @@ s = Secret("NAME")
 s.get() # returns the value
 ```
 
-Note that `s.get()` will not work locally unless `use_local_secrets` is set to `true` in your config.  To pull a Secret value from Cloud requires admin-level permissions.
+Note that `s.get()` will not work locally unless `use_local_secrets` is set to `true` in your config.  Secret values from Cloud are only available during execution.
 
 ## Querying for Secrets