From 91a3d22a9f36b48348a1018e3518273576396b7c Mon Sep 17 00:00:00 2001
From: Paul Hinze <paul@hashicorp.com>
Date: Tue, 31 Mar 2015 18:48:54 -0500
Subject: [PATCH] docs: resource addressing

---
 .../source/docs/commands/apply.html.markdown  |  6 +-
 .../source/docs/commands/plan.html.markdown   |  6 +-
 .../docs/commands/refresh.html.markdown       |  6 +-
 .../resource-addressing.html.markdown         | 57 +++++++++++++++++++
 website/source/layouts/docs.erb               |  4 ++
 5 files changed, 73 insertions(+), 6 deletions(-)
 create mode 100644 website/source/docs/internals/resource-addressing.html.markdown

diff --git a/website/source/docs/commands/apply.html.markdown b/website/source/docs/commands/apply.html.markdown
index 6414f0741..9bb5acdbf 100644
--- a/website/source/docs/commands/apply.html.markdown
+++ b/website/source/docs/commands/apply.html.markdown
@@ -44,8 +44,10 @@ The command-line flags are all optional. The list of available flags are:
 * `-state-out=path` - Path to write updated state file. By default, the
   `-state` path will be used.
 
-* `-target=resource` - Resource to target. Operation will be limited to this
-  resource and its dependencies. This flag can be used multiple times.
+* `-target=resource` - A [Resource
+  Address](/docs/internals/resource-addressing.html) to target. Operation will
+  be limited to this resource and its dependencies. This flag can be used
+  multiple times.
 
 * `-var 'foo=bar'` - Set a variable in the Terraform configuration. This
   flag can be set multiple times.
diff --git a/website/source/docs/commands/plan.html.markdown b/website/source/docs/commands/plan.html.markdown
index fe5e90090..e05c460ce 100644
--- a/website/source/docs/commands/plan.html.markdown
+++ b/website/source/docs/commands/plan.html.markdown
@@ -45,8 +45,10 @@ The command-line flags are all optional. The list of available flags are:
 
 * `-state=path` - Path to the state file. Defaults to "terraform.tfstate".
 
-* `-target=resource` - Resource to target. Operation will be limited to this
-  resource and its dependencies. This flag can be used multiple times.
+* `-target=resource` - A [Resource
+  Address](/docs/internals/resource-addressing.html) to target. Operation will
+  be limited to this resource and its dependencies. This flag can be used
+  multiple times.
 
 * `-var 'foo=bar'` - Set a variable in the Terraform configuration. This
   flag can be set multiple times.
diff --git a/website/source/docs/commands/refresh.html.markdown b/website/source/docs/commands/refresh.html.markdown
index 6d15e1a40..0fc3fc938 100644
--- a/website/source/docs/commands/refresh.html.markdown
+++ b/website/source/docs/commands/refresh.html.markdown
@@ -36,8 +36,10 @@ The command-line flags are all optional. The list of available flags are:
 * `-state-out=path` - Path to write updated state file. By default, the
   `-state` path will be used.
 
-* `-target=resource` - Resource to target. Operation will be limited to this
-  resource and its dependencies. This flag can be used multiple times.
+* `-target=resource` - A [Resource
+  Address](/docs/internals/resource-addressing.html) to target. Operation will
+  be limited to this resource and its dependencies. This flag can be used
+  multiple times.
 
 * `-var 'foo=bar'` - Set a variable in the Terraform configuration. This
   flag can be set multiple times.
diff --git a/website/source/docs/internals/resource-addressing.html.markdown b/website/source/docs/internals/resource-addressing.html.markdown
new file mode 100644
index 000000000..b4b994a88
--- /dev/null
+++ b/website/source/docs/internals/resource-addressing.html.markdown
@@ -0,0 +1,57 @@
+---
+layout: "docs"
+page_title: "Internals: Resource Address"
+sidebar_current: "docs-internals-resource-addressing"
+description: |-
+  Resource addressing is used to target specific resources in a larger
+  infrastructure.
+---
+
+# Resource Addressing
+
+A __Resource Address__ is a string that references a specific resource in a
+larger infrastructure. The syntax of a resource address is:
+
+```
+<resource_type>.<resource_name>[optional fields]
+```
+
+Required fields:
+
+ * `resource_type` - Type of the resource being addressed.
+ * `resource_name` - User-defined name of the resource.
+
+Optional fields may include:
+
+ * `[N]` - where `N` is a `0`-based index into a resource with multiple
+   instances specified by the `count` meta-parameter. Omitting an index when
+   addressing a resource where `count > 1` means that the address references
+   all instances.
+
+
+## Examples
+
+Given a Terraform config that includes:
+
+```
+resource "aws_instance" "web" {
+  # ...
+  count = 4
+}
+```
+
+An address like this:
+
+
+```
+aws_instance.web[3]
+```
+
+Refers to only the last instance in the config, and an address like this:
+
+```
+aws_instance.web
+```
+
+
+Refers to all four "web" instances.
diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb
index a0b31127a..bbdecd4c8 100644
--- a/website/source/layouts/docs.erb
+++ b/website/source/layouts/docs.erb
@@ -215,6 +215,10 @@
 					<li<%= sidebar_current("docs-internals-lifecycle") %>>
 					<a href="/docs/internals/lifecycle.html">Resource Lifecycle</a>
 					</li>
+
+					<li<%= sidebar_current("docs-internals-resource-addressing") %>>
+					<a href="/docs/internals/resource-addressing.html">Resource Addressing</a>
+					</li>
 				</ul>
 				</li>
 			</ul>