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

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 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"].