opentf/website/docs/cli/state/resource-addressing.mdx

---
description: |-
  A resource address is a string that identifies zero or more resource
  instances in your overall configuration.
---

# Resource Addressing

A _resource address_ is a string that identifies zero or more resource
instances in your overall configuration.

An address is made up of two parts:

```
[module path][resource spec]
```

In some contexts OpenTofu might allow for an incomplete resource address that
only refers to a module as a whole, or that omits the index for a
multi-instance resource. In those cases, the meaning depends on the context,
so you'll need to refer to the documentation for the specific feature you
are using which parses resource addresses.

## Module path

A module path addresses a module within the tree of modules. It takes the form:

```
module.module_name[module index]
```

- `module` - Module keyword indicating a child module (non-root). Multiple `module`
  keywords in a path indicate nesting.
- `module_name` - User-defined name of the module.
- `[module index]` - (Optional) [Index](#index-values-for-modules-and-resources)
  to select an instance from a module call that has multiple instances,
  surrounded by square bracket characters (`[` and `]`).

An address without a resource spec, i.e. `module.foo` applies to every resource within
the module if a single module, or all instances of a module if a module has multiple instances.
To address all resources of a particular module instance, include the module index in the address,
such as `module.foo[0]`.

If the module path is omitted, the address applies to the root module.

An example of the `module` keyword delineating between two modules that have multiple instances:

```
module.foo[0].module.bar["a"]
```

## Resource spec

A resource spec addresses a specific resource instance in the selected module.
It has the following syntax:

```
resource_type.resource_name[instance index]
```

- `resource_type` - Type of the resource being addressed.
- `resource_name` - User-defined name of the resource.
- `[instance index]` - (Optional) [Index](#index-values-for-modules-and-resources)
  to select an instance from a resource that has multiple instances,
  surrounded by square bracket characters (`[` and `]`).

A resource spec without a module path prefix matches only resources in the root module.

## Index values for Modules and Resources

The following specifications apply to index values on modules and resources with multiple instances:

- `[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 OpenTofu config that includes:

```hcl
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.

### for_each Example

Given a OpenTofu config that includes:

```hcl
resource "aws_instance" "web" {
  # ...
  for_each = {
    "tofu": "value1",
    "resource":  "value2",
    "indexing":  "value3",
    "example":   "value4",
  }
}
```

An address like this:

```
aws_instance.web["example"]
```

Refers to only the "example" instance in the config, and resolves to "value4".

## Resource Addresses on the Command Line

When using resource addresses directly in command line arguments such as
the `-target`, `-exclude`, and `-replace` planning options, the punctuation
characters in the resource address syntax might conflict with special
interpretation of those characters by the shell you are using to run
OpenTofu.

To avoid this, you must ensure that those characters are properly quoted
or escaped so that your shell will pass them literally to OpenTofu.
The syntax for doing so varies depending on your shell or command
interpreter:

- For Unix-style shells such as `bash`, write the resource address in
  single quotes (`'`):

    ```bash
    tofu apply -target='aws_instance.example["foo"]'
    ```

    If you need to specify an instance key string that includes a
    single quote character, use two separate single-quoted sequences
    with an escaped single quote between them. For example,
    the following includes the instance key `"example'foo"`:

    ```bash
    tofu apply -target='aws_instance.example["example'\''foo"]'
    ```

- For PowerShell 7.3 or later, write the resource address in single
  quotes (`'`):

    ```powershell
    tofu apply -target='aws_instance.example["foo"]'
    ```

    Older versions of PowerShell have different requirements. For more
    information, refer to
    [Passing arguments that contain quote characters](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-7.5#passing-arguments-that-contain-quote-characters).

    If you need to specify an instance key string that includes a
    single quote character, use two consecutive single quotes to
    represent a single literal quote. For example, the following
    includes the instance key `"example'foo"`:

    ```powershell
    tofu apply -target='aws_instance.example["example''foo"]'
    ```

- For Windows Command Prompt (`cmd.exe`), write the resource address in
  double quotes (`"`) and escape any quotes from the resource address
  using a backslash (`\`):

    ```batchfile
    tofu apply -target="aws_instance.example[\"foo\"]"
    ```

## Resource Addresses in Targeting Files

The `-target-file` and `-exclude-file`
[planning options](../commands/plan.mdx#planning-options) read resource
addresses from a separate file that can contain zero or more resource
addresses.

OpenTofu interprets a targeting file on a line-by-line basis. The
content of each line must be one of the following:

- A resource address using the syntax described above, in which case
  OpenTofu adds the address to the set of target addresses.
- A comment starting with the `#` character, in which case OpenTofu
  ignores the line completely.
- A blank line consisting only of zero or more space characters, in
  which case OpenTofu also ignores the line completely.

For example, the following is a valid targeting file specifying a
number of resource addresses that might need to be created first
when applying a certain configuration for the first time:

```hcl
# These modules must be targeted during initial creation.
module.network
module.cluster

# The following resources must also be included on initial
# creation.
aws_iam_role.all["base"]
aws_iam_role_policy.all["base"]
```

The targeting file above would match all instances of all resources
whose addresses begin with `module.network` or `module.cluster`, and
also the specific resource instances `aws_iam_role.all["base"]` and
`aws_iam_role_policy.all["base"]`.