docs: resource addressing

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
+* `-target=resource` - A [Resource
-  resource and its dependencies. This flag can be used multiple times.
+  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.

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
+* `-target=resource` - A [Resource
-  resource and its dependencies. This flag can be used multiple times.
+  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.

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
+* `-target=resource` - A [Resource
-  resource and its dependencies. This flag can be used multiple times.
+  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.

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.

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>