Update refernce documentation for secrets

**What**
- Add notes and describe how to read secrets from files in openfaas
- Add a final note to the end of the authentication refernce directing
people to the `secrets` reference.

**Why**
- This improves the walk-through and makes it clear how to write a
function that uses secrets _and_ how to deploy it

Signed-off-by: Lucas Roesler <roesler.lucas@gmail.com>

Author: LucasRoesler

docs/reference/authentication.md

@@ -25,5 +25,4 @@ Functions are exposed at:
 
 Functions exposed on OpenFaaS often do not need to have authentication enabled, this is because they may be responding to webhooks from an external system such as GitHub or Patreon. Neither GitHub, nor Patreon will support authenticating with OAuth or basic authentication strategies, but rely on HMAC.
 
-HMAC involves a shared symmetric secret - both parties store the key securely. The sender computes a hash of the body of the request with their symmetric key and sends this data to the receiver along with the has value in the HTTP header. The receiver then computes a hash of the body with their copy of the key and checks that this matches what the sender supplied in the HTTP header.
-
+HMAC involves a shared symmetric secret - both parties store the key securely. The sender computes a hash of the body of the request with their symmetric key and sends this data to the receiver along with the has value in the HTTP header. The receiver then computes a hash of the body with their copy of the key and checks that this matches what the sender supplied in the HTTP header. See the reference on [secrets](./secrets.md) for a walk-through on using secret values with functions.

docs/reference/secrets.md

@@ -38,6 +38,29 @@ docker secret create secret-api-key ~/secrets/secret_api_key.txt
 
 ## Use the secret in your function
 
+Secrets are mounted as files to `/var/openfaas/secrets` inside your function. Using secrets is as simple as adding code to read the value from `/var/openfaas/secrets/secret-api-key`.
+
+_Note_: prior to version `0.8.2` secrets were mounted to `/run/secrets`. The example functions demonstrate a smooth upgrade implementation.
+
+A simple `go` implementation could look like this
+
+```go
+func getAPISecret(secretName string) (secretBytes []byte, err error) {
+	// read from the openfaas secrets folder
+	secretBytes, err = ioutil.ReadFile("/var/openfaas/secrets/" + secretName)
+	if err != nil {
+		// read from the original location for backwards compatibility with openfaas <= 0.8.2
+		secretBytes, err = ioutil.ReadFile("/run/secrets/" + secretName)
+	}
+
+	return secretBytes, err
+}
+```
+
+This example comes from the [`ApiKeyProtected`](https://github.com/openfaas/faas/tree/master/sample-functions/ApiKeyProtected-Secrets) sample function.
+
+## Deploy a function with secrets
+
 Now, update your stack file to include the secret:
 
 ```yaml