Merge pull request serverless#4304 from serverless/DavidWells-patch-1

Update variables.md

docs/providers/aws/guide/variables.md

@@ -18,14 +18,18 @@ They are especially useful when providing secrets for your service to use and wh
 
 ## Syntax
 
-To use variables, you will need to reference values enclosed in `${}`. 
+To use variables, you will need to reference values enclosed in `${}` brackets. 
 
-```
-yamlKeyXYZ: ${variableSource}
-# see current variable sources list below
+```yml
+# serverless.yml file
+yamlKeyXYZ: ${variableSource} # see list of current variable sources below
+# this is an example of providing a default value as the second parameter
+otherYamlKey: ${variableSource, defaultValue}
 ```
 
-You can define your own variable syntax (regex) if it conflicts with CloudFormation's syntax
+You can define your own variable syntax (regex) if it conflicts with CloudFormation's syntax. 
+
+**Note:** You can only use variables in `serverless.yml` property **values**, not property keys. So you can't use variables to generate dynamic logical IDs in the custom resources section for example.
 
 ## Current variable sources: 
 
@@ -38,9 +42,32 @@ You can define your own variable syntax (regex) if it conflicts with CloudFormat
 - [CloudFormation stack outputs](https://serverless.com/framework/docs/providers/aws/guide/variables#reference-cloudformation-outputs)
 - [properties exported from Javascript files (sync or async)](https://serverless.com/framework/docs/providers/aws/guide/variables#reference-variables-in-javascript-files)
 
+## Recursively reference properties
+
 You can also **Recursively reference properties** with the variable system. This means you can combine multiple values and variable sources for a lot of flexibility.
 
-**Note:** You can only use variables in `serverless.yml` property **values**, not property keys. So you can't use variables to generate dynamic logical IDs in the custom resources section for example.
+For example:
+
+```yml
+provider:
+  name: aws
+  stage: ${opt:stage, 'dev'}
+  environment:
+    MY_SECRET: ${file(./config.${self:provider.stage}.json):CREDS}
+```
+
+If `sls deploy --stage qa` is ran, the option `stage=qa` is used inside the `${file(./config.${self:provider.stage}.json):CREDS}` variable and it will resolve the `config.qa.json` file and use the `CREDS` key defined. 
+
+**How that works:**
+
+1. stage is set to `qa` from the option supplied to the `sls deploy --stage qa` command
+2. `${self:provider.stage}` resolves to `qa` and is used in `${file(./config.${self:provider.stage}.json):CREDS}`
+3. `${file(./config.qa.stage}.json):CREDS}` is found & the `CREDS` value is read
+4. `MY_SECRET` value is set
+
+Likewise, if `sls deploy --stage prod` is ran the `config.prod.json` file would be found and used.
+
+If no `--stage` flag is provided, the second parameter defined in `${opt:stage, 'dev'}` a.k.a `dev` will be used and result in `${file(./config.dev.json):CREDS}`.
 
 ## Reference Properties In serverless.yml
 To self-reference properties in `serverless.yml`, use the `${self:someProperty}` syntax in your `serverless.yml`. `someProperty` can contain the empty string for a top-level self-reference or a dotted attribute reference to any depth of attribute, so you can go as shallow or deep in the object tree as you want.