From 988b0325a1a235b5e0c0a70861668f396eacf186 Mon Sep 17 00:00:00 2001
From: Seth Vargo <sethvargo@gmail.com>
Date: Sun, 21 Aug 2016 15:17:31 -0400
Subject: [PATCH] Add more output grammar and CLI examples

---
 .../source/docs/commands/output.html.markdown | 53 +++++++++++++++++--
 .../source/docs/configuration/outputs.html.md | 28 ++++++----
 2 files changed, 69 insertions(+), 12 deletions(-)

diff --git a/website/source/docs/commands/output.html.markdown b/website/source/docs/commands/output.html.markdown
index d42f7cae2..79813d48c 100644
--- a/website/source/docs/commands/output.html.markdown
+++ b/website/source/docs/commands/output.html.markdown
@@ -15,8 +15,9 @@ an output variable from the state file.
 
 Usage: `terraform output [options] [NAME]`
 
-With no additional arguments, `output` will display all the outputs for the root module.
-If an output `NAME` is specified, only the value of that output is printed.
+With no additional arguments, `output` will display all the outputs for
+the root module. If an output `NAME` is specified, only the value of that
+output is printed.
 
 The command-line flags are all optional. The list of available flags are:
 
@@ -24,9 +25,55 @@ The command-line flags are all optional. The list of available flags are:
     a key per output. If `NAME` is specified, only the output specified will be
     returned. This can be piped into tools such as `jq` for further processing.
 * `-state=path` - Path to the state file. Defaults to "terraform.tfstate".
-  Ignored when [remote state](/docs/state/remote/index.html) is used.
+    Ignored when [remote state](/docs/state/remote/index.html) is used.
 * `-module=module_name` - The module path which has needed output.
     By default this is the root path. Other modules can be specified by
     a period-separated list. Example: "foo" would reference the module
     "foo" but "foo.bar" would reference the "bar" module in the "foo"
     module.
+
+## Examples
+
+These examples assume the following Terraform output snippet.
+
+```ruby
+output "lb_address" {
+  value = "${aws_alb.web.public_dns}"
+}
+
+output "instance_ips" {
+  value = "${aws_instance.web.*.public_ip}"
+}
+```
+
+To list all outputs:
+
+```text
+$ terraform output
+```
+
+To query for the DNS address of the load balancer:
+
+```text
+$ terraform output lb_address
+my-app-alb-1657023003.us-east-1.elb.amazonaws.com
+```
+
+To query for all instance IP addresses:
+
+```text
+$ terraform output instance_ips
+test = [
+    54.43.114.12,
+    52.122.13.4,
+    52.4.116.53
+]
+```
+
+To query for a particular value in a list, use `-json` and a JSON
+command-line parser such as [jq](https://stedolan.github.io/jq/).
+For example, to query for the first instance's IP address:
+
+```text
+$ terraform output -json instance_ips | jq '.value[0]'
+```
diff --git a/website/source/docs/configuration/outputs.html.md b/website/source/docs/configuration/outputs.html.md
index f3bc68e6b..8cac18a8d 100644
--- a/website/source/docs/configuration/outputs.html.md
+++ b/website/source/docs/configuration/outputs.html.md
@@ -16,21 +16,31 @@ is covered in more detail in the
 This page covers configuration syntax for outputs.
 
 Terraform knows a lot about the infrastructure it manages.
-Most resources have a handful or even a dozen or more attributes
-associated with it. Outputs are a way to easily extract
-information.
+Most resources have attributes associated with them, and
+outputs are a way to easily extract and query that information.
 
-This page assumes you're familiar with the
+This page assumes you are familiar with the
 [configuration syntax](/docs/configuration/syntax.html)
 already.
 
 ## Example
 
-An output configuration looks like the following:
+A simple output configuration looks like the following:
 
-```
+```ruby
 output "address" {
- value = "${aws_instance.web.public_dns}"
+  value = "${aws_instance.db.public_dns}"
+}
+```
+
+This will output a string value corresponding to the public
+DNS address of the Terraform-defined AWS instance named "db". It
+is possible to export complex data types like maps and strings as
+well:
+
+```ruby
+output "addresses" {
+  value = ["${aws_instance.web.*.public_dns}"]
 }
 ```
 
@@ -54,7 +64,7 @@ These are the parameters that can be set:
 
 The full syntax is:
 
-```
+```ruby
 output NAME {
   value = VALUE
 }
@@ -65,7 +75,7 @@ output NAME {
 Outputs can be marked as containing sensitive material by setting the
 `sensitive` attribute to `true`, like this:
 
-```
+```ruby
 output "sensitive" {
   sensitive = true
   value     = VALUE