From fd88c98c20872d332c69b5651ea68310de24fdd5 Mon Sep 17 00:00:00 2001
From: Martin Atkins <mart@degeneration.co.uk>
Date: Thu, 17 Aug 2017 10:21:59 -0700
Subject: [PATCH] website: documentation for local values

---
 website/docs/configuration/locals.html.md | 59 +++++++++++++++++++++++
 website/layouts/docs.erb                  |  4 ++
 2 files changed, 63 insertions(+)
 create mode 100644 website/docs/configuration/locals.html.md

diff --git a/website/docs/configuration/locals.html.md b/website/docs/configuration/locals.html.md
new file mode 100644
index 000000000000..6067c5486b22
--- /dev/null
+++ b/website/docs/configuration/locals.html.md
@@ -0,0 +1,59 @@
+---
+layout: "docs"
+page_title: "Configuring Local Values"
+sidebar_current: "docs-config-locals"
+description: |-
+  Local values assign a name to an expression that can then be used multiple times
+  within a module.
+---
+
+# Local Value Configuration
+
+Local values assign a name to an expression, that can then be used multiple
+times within a module.
+
+Comparing modules to functions in a traditional programming language,
+if [variables](./variables.html) are analogous to function arguments and
+[outputs](./outputs.html) are analogous to function return values then
+_local values_ are comparable to a function's local variables.
+
+This page assumes you're already familiar with
+[the configuration syntax](/docs/configuration/syntax.html).
+
+## Example
+
+Local values are defined in `locals` blocks:
+
+```hcl
+# Ids for multiple sets of EC2 instances, merged together
+locals {
+  instance_ids = "${concat(aws_instance.blue.*.id, aws_instance.green.*.id)}"
+}
+
+# A computed default name prefix
+locals {
+  default_name_prefix = "${var.project_name}-web"
+  name_prefix         = "${var.name_prefix != "" ? var.name_prefix : local.default_name_prefix}"
+}
+```
+
+## Description
+
+The `locals` block defines one or more local variables within a module.
+Each `locals` block can have as many locals as needed, and there can be any
+number of `locals` blocks within a module.
+
+The names given for the items in the `locals` block must be unique throughout
+a module. The given value can be any expression that is valid within
+the current module.
+
+The expression of a local value can refer to other locals, but as usual
+reference cycles are not allowed. That is, a local cannot refer to itself
+or to a variable that refers (directly or indirectly) back to it.
+
+It's recommended to group together logically-related local values into
+a single block, particulary if they depend on each other. This will help
+the reader understand the relationships between variables. Conversely,
+prefer to define _unrelated_ local values in _separate_ blocks, and consider
+annotating each block with a comment describing any context common to all
+of the enclosed locals.
diff --git a/website/layouts/docs.erb b/website/layouts/docs.erb
index 89a893545315..5457337f99b6 100644
--- a/website/layouts/docs.erb
+++ b/website/layouts/docs.erb
@@ -40,6 +40,10 @@
             <a href="/docs/configuration/outputs.html">Outputs</a>
           </li>
 
+          <li<%= sidebar_current("docs-config-locals") %>>
+            <a href="/docs/configuration/locals.html">Local Values</a>
+          </li>
+
           <li<%= sidebar_current("docs-config-modules") %>>
             <a href="/docs/configuration/modules.html">Modules</a>
           </li>