Merge pull request #22318 from hashicorp/d-cli-quote-resource-addresses

docs: Additional for_each commands and resource addressing documentation

website/docs/commands/import.html.md

@@ -110,18 +110,50 @@ specifying `-config=""` (empty string). This is useful in situations where
 you want to manually configure the provider because your configuration
 may not be valid.
 
-## Example: AWS Instance
+## Example: Import into Resource
 
-This example will import an AWS instance:
+This example will import an AWS instance into the `aws_instance` resource named `foo`:
 
 ```shell
 $ terraform import aws_instance.foo i-abcd1234
 ```
 
-## Example: Import to Module
+## Example: Import into Module
 
-The example below will import an AWS instance into a module:
+The example below will import an AWS instance into the `aws_instance` resource named `bar` into a module named `foo`:
 
 ```shell
 $ terraform import module.foo.aws_instance.bar i-abcd1234
 ```
+
+## Example: Import into Resource configured with count
+
+The example below will import an AWS instance into the first instance of the `aws_instance` resource named `baz` configured with
+[`count`](/docs/configuration/resources.html#count-multiple-resource-instances-by-count):
+
+```shell
+$ terraform import 'aws_instance.baz[0]' i-abcd1234
+```
+
+## Example: Import into Resource configured with for_each
+
+The example below will import an AWS instance into the `"example"` instance of the `aws_instance` resource named `baz` configured with
+[`for_each`](/docs/configuration/resources.html#for_each-multiple-resource-instances-defined-by-a-map-or-set-of-strings):
+
+Linux, Mac OS, and UNIX:
+
+```shell
+$ terraform import 'aws_instance.baz["example"]' i-abcd1234
+```
+
+PowerShell:
+
+```shell
+$ terraform import 'aws_instance.baz[\"example\"]' i-abcd1234
+```
+
+Windows `cmd.exe`:
+
+```shell
+$ terraform import aws_instance.baz[\"example\"] i-abcd1234
+```

website/docs/commands/state/mv.html.md

@@ -59,36 +59,69 @@ The command-line flags are all optional. The list of available flags are:
 
 ## Example: Rename a Resource
 
-The example below renames a single resource:
+The example below renames the `packet_device` resource named `worker` to `helper`:
 
-```
-$ terraform state mv aws_instance.foo aws_instance.bar
+```shell
+$ terraform state mv 'packet_device.worker' 'packet_device.helper'
 ```
 
 ## Example: Move a Resource Into a Module
 
-The example below moves a resource into a module. The module will be
-created if it doesn't exist.
+The example below moves the `packet_device` resource named `worker` into a module
+named `app`. The module will be created if it doesn't exist.
 
-```
-$ terraform state mv aws_instance.foo module.web
+```shell
+$ terraform state mv 'packet_device.worker' 'module.app'
 ```
 
 ## Example: Move a Module Into a Module
 
-The example below moves a module into another module.
+The example below moves the module named `app` under the module named `parent`.
 
-```
-$ terraform state mv module.foo module.parent.module.foo
+```shell
+$ terraform state mv 'module.app' 'module.parent.module.app'
 ```
 
 ## Example: Move a Module to Another State
 
-The example below moves a module into another state file. This removes
+The example below moves the module named `app` into another state file. This removes
 the module from the original state file and adds it to the destination.
 The source and destination are the same meaning we're keeping the same name.
 
+```shell
+$ terraform state mv -state-out=other.tfstate 'module.app' 'module.app'
 ```
-$ terraform state mv -state-out=other.tfstate \
-    module.web module.web
+
+## Example: Move a Resource configured with count
+
+The example below moves the first instance of a `packet_device` resource named `worker` configured with
+[`count`](/docs/configuration/resources.html#count-multiple-resource-instances-by-count) to
+the first instance of a resource named `helper` also configured with `count`:
+
+```shell
+$ terraform state mv 'packet_device.worker[0]' 'packet_device.helper[0]'
+```
+
+## Example: Move a Resource configured with for_each
+
+The example below moves the `"example123"` instance of a `packet_device` resource named `worker` configured with
+[`for_each`](/docs/configuration/resources.html#for_each-multiple-resource-instances-defined-by-a-map-or-set-of-strings)
+to the `"example456"` instance of a resource named `helper` also configuring `for_each`:
+
+Linux, Mac OS, and UNIX:
+
+```shell
+$ terraform state mv 'packet_device.worker["example123"]' 'packet_device.helper["example456"]'
+```
+
+PowerShell:
+
+```shell
+$ terraform state mv 'packet_device.worker[\"example123\"]' 'packet_device.helper[\"example456\"]'
+```
+
+Windows `cmd.exe`:
+
+```shell
+$ terraform state mv packet_device.worker[\"example123\"] packet_device.helper[\"example456\"]
 ```

website/docs/commands/state/rm.html.md

@@ -53,16 +53,56 @@ The command-line flags are all optional. The list of available flags are:
 
 ## Example: Remove a Resource
 
-The example below removes a single resource in a module:
+The example below removes the `packet_device` resource named `worker`:
 
-```
-$ terraform state rm module.foo.packet_device.worker[0]
+```shell
+$ terraform state rm 'packet_device.worker'
 ```
 
 ## Example: Remove a Module
 
-The example below removes an entire module:
+The example below removes the entire module named `foo`:
 
+```shell
+$ terraform state rm 'module.foo'
 ```
-$ terraform state rm module.foo
+
+## Example: Remove a Module Resource
+
+The example below removes the `packet_device` resource named `worker` inside a module named `foo`:
+
+```shell
+$ terraform state rm 'module.foo.packet_device.worker'
+```
+
+## Example: Remove a Resource configured with count
+
+The example below removes the first instance of a `packet_device` resource named `worker` configured with
+[`count`](/docs/configuration/resources.html#count-multiple-resource-instances-by-count):
+
+```shell
+$ terraform state rm 'packet_device.worker[0]'
+```
+
+## Example: Remove a Resource configured with for_each
+
+The example below removes the `"example"` instance of a `packet_device` resource named `worker` configured with
+[`for_each`](/docs/configuration/resources.html#for_each-multiple-resource-instances-defined-by-a-map-or-set-of-strings):
+
+Linux, Mac OS, and UNIX:
+
+```shell
+$ terraform state rm 'packet_device.worker["example"]'
+```
+
+PowerShell:
+
+```shell
+$ terraform state rm 'packet_device.worker[\"example\"]'
+```
+
+Windows `cmd.exe`:
+
+```shell
+$ terraform state rm packet_device.worker[\"example\"]
 ```

website/docs/commands/state/show.html.md

@@ -34,10 +34,10 @@ The command-line flags are all optional. The list of available flags are:
 
 ## Example: Show a Resource
 
-The example below shows a resource:
+The example below shows a `packet_device` resource named `worker`:
 
 ```
-$ terraform state show module.foo.packet_device.worker[0]
+$ terraform state show 'packet_device.worker'
 id                = 6015bg2b-b8c4-4925-aad2-f0671d5d3b13
 billing_cycle     = hourly
 created           = 2015-12-17T00:06:56Z
@@ -46,3 +46,43 @@ hostname          = prod-xyz01
 locked            = false
 ...
 ```
+
+## Example: Show a Module Resource
+
+The example below shows a `packet_device` resource named `worker` inside a module named `foo`:
+
+```shell
+$ terraform state show 'module.foo.packet_device.worker'
+```
+
+## Example: Show a Resource configured with count
+
+The example below shows the first instance of a `packet_device` resource named `worker` configured with
+[`count`](/docs/configuration/resources.html#count-multiple-resource-instances-by-count):
+
+```shell
+$ terraform state show 'packet_device.worker[0]'
+```
+
+## Example: Show a Resource configured with for_each
+
+The example below shows the `"example"` instance of a `packet_device` resource named `worker` configured with
+[`for_each`](/docs/configuration/resources.html#for_each-multiple-resource-instances-defined-by-a-map-or-set-of-strings):
+
+Linux, Mac OS, and UNIX:
+
+```shell
+$ terraform state show 'packet_device.worker["example"]'
+```
+
+PowerShell:
+
+```shell
+$ terraform state show 'packet_device.worker[\"example\"]'
+```
+
+Windows `cmd.exe`:
+
+```shell
+$ terraform state show packet_device.worker[\"example\"]
+```

website/docs/internals/resource-addressing.html.markdown

@@ -33,23 +33,32 @@ __Resource spec__:
 A resource spec addresses a specific resource in the config. It takes the form:
 
 ```
-resource_type.resource_name[N]
+resource_type.resource_name[resource index]
 ```
 
  * `resource_type` - Type of the resource being addressed.
  * `resource_name` - User-defined name of the resource.
- * `[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.
+ * `[resource index]` - an optional index into a resource with multiple
+   instances, surrounded by square brace characters (`[` and `]`).
 
 -> In Terraform v0.12 and later, a resource spec without a module path prefix
 matches only resources in the root module. In earlier versions, a resource spec
 without a module path prefix will match resources with the same type and name
 in any descendent module.
 
+__Resource index__:
+
+ * `[N]` where `N` is a `0`-based numerical index into a resource with multiple
+   instances specified by the `count` meta-argument. Omitting an index when
+   addressing a resource where `count > 1` means that the address references
+   all instances.
+ * `["INDEX"]` where `INDEX` is a alphanumerical key index into a resource with
+   multiple instances specified by the `for_each` meta-argument.
+
 ## Examples
 
+### count Example
+
 Given a Terraform config that includes:
 
 ```hcl
@@ -72,3 +81,27 @@ aws_instance.web
 ```
 
 Refers to all four "web" instances.
+
+### for_each Example
+
+Given a Terraform config that includes:
+
+```hcl
+resource "aws_instance" "web" {
+  # ...
+  for_each = {
+    "terraform": "value1",
+    "resource":  "value2",
+    "indexing":  "value3",
+    "example":   "value4",
+  }
+}
+```
+
+An address like this:
+
+```
+aws_instance.web["example"]
+```
+
+Refers to only the "example" instance in the config.