website: Break up main Modules and Module Development pages
This one is a lot like the previous two commits, but slightly more complex:
- Only adding one new meta-argument page, for `providers`; otherwise, it just
re-uses the dual-purpose pages I made in the resources commit.
- About that `providers` argument: The stuff that was relevant to consumers of a
module went in that meta-argument page, but there was also a huge deep dive on
how the _author_ of a re-usable module should handle provider configurations
in cases where inheriting the default providers isn't sufficient. THAT, I
moved into a new page in the module development section. (For the consumer of
a module, this should all be an implementation detail; the module README
should tell you which aliased providers you need to configure and pass, and
then you just do it, without worrying about proxy configuration blocks etc.)
- The "standard module structure" recommendations in the main module development
page gets a page of its own, to make it more prominent and discoverable.
- Same deal with using the old URL as a landing page, at least for the main
module calls page. It didn't seem necessary for the module development page.
2020-11-12 21:21:35 -05:00
---
2021-12-14 21:41:17 -05:00
description: >-
Modules are containers for multiple resources that are used together in
configurations. Learn how to call one module from another and access module
output.
website: Break up main Modules and Module Development pages
This one is a lot like the previous two commits, but slightly more complex:
- Only adding one new meta-argument page, for `providers`; otherwise, it just
re-uses the dual-purpose pages I made in the resources commit.
- About that `providers` argument: The stuff that was relevant to consumers of a
module went in that meta-argument page, but there was also a huge deep dive on
how the _author_ of a re-usable module should handle provider configurations
in cases where inheriting the default providers isn't sufficient. THAT, I
moved into a new page in the module development section. (For the consumer of
a module, this should all be an implementation detail; the module README
should tell you which aliased providers you need to configure and pass, and
then you just do it, without worrying about proxy configuration blocks etc.)
- The "standard module structure" recommendations in the main module development
page gets a page of its own, to make it more prominent and discoverable.
- Same deal with using the old URL as a landing page, at least for the main
module calls page. It didn't seem necessary for the module development page.
2020-11-12 21:21:35 -05:00
---
# Module Blocks
A _module_ is a container for multiple resources that are used together.
2023-09-21 05:57:47 -04:00
Every OpenTofu configuration has at least one module, known as its
2024-07-22 11:35:59 -04:00
_root module_, which consists of the resources defined in the `.tf` and `.tofu`
files in the main working directory.
website: Break up main Modules and Module Development pages
This one is a lot like the previous two commits, but slightly more complex:
- Only adding one new meta-argument page, for `providers`; otherwise, it just
re-uses the dual-purpose pages I made in the resources commit.
- About that `providers` argument: The stuff that was relevant to consumers of a
module went in that meta-argument page, but there was also a huge deep dive on
how the _author_ of a re-usable module should handle provider configurations
in cases where inheriting the default providers isn't sufficient. THAT, I
moved into a new page in the module development section. (For the consumer of
a module, this should all be an implementation detail; the module README
should tell you which aliased providers you need to configure and pass, and
then you just do it, without worrying about proxy configuration blocks etc.)
- The "standard module structure" recommendations in the main module development
page gets a page of its own, to make it more prominent and discoverable.
- Same deal with using the old URL as a landing page, at least for the main
module calls page. It didn't seem necessary for the module development page.
2020-11-12 21:21:35 -05:00
A module can call other modules, which lets you include the child module's
resources into the configuration in a concise way. Modules
can also be called multiple times, either within the same configuration or
in separate configurations, allowing resource configurations to be packaged
and re-used.
This page describes how to call one module from another. For more information
2024-04-24 07:24:30 -04:00
about creating re-usable child modules, see [Module Development](../../language/modules/develop/index.mdx).
website: Break up main Modules and Module Development pages
This one is a lot like the previous two commits, but slightly more complex:
- Only adding one new meta-argument page, for `providers`; otherwise, it just
re-uses the dual-purpose pages I made in the resources commit.
- About that `providers` argument: The stuff that was relevant to consumers of a
module went in that meta-argument page, but there was also a huge deep dive on
how the _author_ of a re-usable module should handle provider configurations
in cases where inheriting the default providers isn't sufficient. THAT, I
moved into a new page in the module development section. (For the consumer of
a module, this should all be an implementation detail; the module README
should tell you which aliased providers you need to configure and pass, and
then you just do it, without worrying about proxy configuration blocks etc.)
- The "standard module structure" recommendations in the main module development
page gets a page of its own, to make it more prominent and discoverable.
- Same deal with using the old URL as a landing page, at least for the main
module calls page. It didn't seem necessary for the module development page.
2020-11-12 21:21:35 -05:00
## Calling a Child Module
To _call_ a module means to include the contents of that module into the
configuration with specific values for its
2024-04-24 07:24:30 -04:00
[input variables](../../language/values/variables.mdx). Modules are called
website: Break up main Modules and Module Development pages
This one is a lot like the previous two commits, but slightly more complex:
- Only adding one new meta-argument page, for `providers`; otherwise, it just
re-uses the dual-purpose pages I made in the resources commit.
- About that `providers` argument: The stuff that was relevant to consumers of a
module went in that meta-argument page, but there was also a huge deep dive on
how the _author_ of a re-usable module should handle provider configurations
in cases where inheriting the default providers isn't sufficient. THAT, I
moved into a new page in the module development section. (For the consumer of
a module, this should all be an implementation detail; the module README
should tell you which aliased providers you need to configure and pass, and
then you just do it, without worrying about proxy configuration blocks etc.)
- The "standard module structure" recommendations in the main module development
page gets a page of its own, to make it more prominent and discoverable.
- Same deal with using the old URL as a landing page, at least for the main
module calls page. It didn't seem necessary for the module development page.
2020-11-12 21:21:35 -05:00
from within other modules using `module` blocks:
```hcl
module "servers" {
source = "./app-cluster"
servers = 5
}
```
A module that includes a `module` block like this is the _calling module_ of the
child module.
The label immediately after the `module` keyword is a local name, which the
calling module can use to refer to this instance of the module.
Within the block body (between `{` and `}`) are the arguments for the module.
Module calls use the following kinds of arguments:
- The `source` argument is mandatory for all modules.
- The `version` argument is recommended for modules from a registry.
2024-04-24 07:24:30 -04:00
- Most other arguments correspond to [input variables](../../language/values/variables.mdx)
website: Break up main Modules and Module Development pages
This one is a lot like the previous two commits, but slightly more complex:
- Only adding one new meta-argument page, for `providers`; otherwise, it just
re-uses the dual-purpose pages I made in the resources commit.
- About that `providers` argument: The stuff that was relevant to consumers of a
module went in that meta-argument page, but there was also a huge deep dive on
how the _author_ of a re-usable module should handle provider configurations
in cases where inheriting the default providers isn't sufficient. THAT, I
moved into a new page in the module development section. (For the consumer of
a module, this should all be an implementation detail; the module README
should tell you which aliased providers you need to configure and pass, and
then you just do it, without worrying about proxy configuration blocks etc.)
- The "standard module structure" recommendations in the main module development
page gets a page of its own, to make it more prominent and discoverable.
- Same deal with using the old URL as a landing page, at least for the main
module calls page. It didn't seem necessary for the module development page.
2020-11-12 21:21:35 -05:00
defined by the module. (The `servers` argument in the example above is one of
these.)
2023-09-21 05:57:47 -04:00
- OpenTofu defines a few other meta-arguments that can be used with all
website: Break up main Modules and Module Development pages
This one is a lot like the previous two commits, but slightly more complex:
- Only adding one new meta-argument page, for `providers`; otherwise, it just
re-uses the dual-purpose pages I made in the resources commit.
- About that `providers` argument: The stuff that was relevant to consumers of a
module went in that meta-argument page, but there was also a huge deep dive on
how the _author_ of a re-usable module should handle provider configurations
in cases where inheriting the default providers isn't sufficient. THAT, I
moved into a new page in the module development section. (For the consumer of
a module, this should all be an implementation detail; the module README
should tell you which aliased providers you need to configure and pass, and
then you just do it, without worrying about proxy configuration blocks etc.)
- The "standard module structure" recommendations in the main module development
page gets a page of its own, to make it more prominent and discoverable.
- Same deal with using the old URL as a landing page, at least for the main
module calls page. It didn't seem necessary for the module development page.
2020-11-12 21:21:35 -05:00
modules, including `for_each` and `depends_on`.
### Source
All modules **require** a `source` argument, which is a meta-argument defined by
2023-09-21 05:57:47 -04:00
OpenTofu. Its value is either the path to a local directory containing the
module's configuration files, or a remote module source that OpenTofu should
2024-06-24 09:13:07 -04:00
download and use. For more information on
2024-04-24 07:24:30 -04:00
possible values for this argument, see [Module Sources](../../language/modules/sources.mdx).
website: Break up main Modules and Module Development pages
This one is a lot like the previous two commits, but slightly more complex:
- Only adding one new meta-argument page, for `providers`; otherwise, it just
re-uses the dual-purpose pages I made in the resources commit.
- About that `providers` argument: The stuff that was relevant to consumers of a
module went in that meta-argument page, but there was also a huge deep dive on
how the _author_ of a re-usable module should handle provider configurations
in cases where inheriting the default providers isn't sufficient. THAT, I
moved into a new page in the module development section. (For the consumer of
a module, this should all be an implementation detail; the module README
should tell you which aliased providers you need to configure and pass, and
then you just do it, without worrying about proxy configuration blocks etc.)
- The "standard module structure" recommendations in the main module development
page gets a page of its own, to make it more prominent and discoverable.
- Same deal with using the old URL as a landing page, at least for the main
module calls page. It didn't seem necessary for the module development page.
2020-11-12 21:21:35 -05:00
The same source address can be specified in multiple `module` blocks to create
multiple copies of the resources defined within, possibly with different
variable values.
After adding, removing, or modifying `module` blocks, you must re-run
2023-09-21 05:57:47 -04:00
`tofu init` to allow OpenTofu the opportunity to adjust the installed
website: Break up main Modules and Module Development pages
This one is a lot like the previous two commits, but slightly more complex:
- Only adding one new meta-argument page, for `providers`; otherwise, it just
re-uses the dual-purpose pages I made in the resources commit.
- About that `providers` argument: The stuff that was relevant to consumers of a
module went in that meta-argument page, but there was also a huge deep dive on
how the _author_ of a re-usable module should handle provider configurations
in cases where inheriting the default providers isn't sufficient. THAT, I
moved into a new page in the module development section. (For the consumer of
a module, this should all be an implementation detail; the module README
should tell you which aliased providers you need to configure and pass, and
then you just do it, without worrying about proxy configuration blocks etc.)
- The "standard module structure" recommendations in the main module development
page gets a page of its own, to make it more prominent and discoverable.
- Same deal with using the old URL as a landing page, at least for the main
module calls page. It didn't seem necessary for the module development page.
2020-11-12 21:21:35 -05:00
modules. By default this command will not upgrade an already-installed module;
use the `-upgrade` option to instead upgrade to the newest available version.
### Version
When using modules installed from a module registry, we recommend explicitly
constraining the acceptable version numbers to avoid unexpected or unwanted
changes.
Use the `version` argument in the `module` block to specify versions:
```shell
module "consul" {
source = "hashicorp/consul/aws"
version = "0.0.5"
servers = 3
}
```
2024-04-24 07:24:30 -04:00
The `version` argument accepts a [version constraint string](../../language/expressions/version-constraints.mdx).
2023-09-21 05:57:47 -04:00
OpenTofu will use the newest installed version of the module that meets the
website: Break up main Modules and Module Development pages
This one is a lot like the previous two commits, but slightly more complex:
- Only adding one new meta-argument page, for `providers`; otherwise, it just
re-uses the dual-purpose pages I made in the resources commit.
- About that `providers` argument: The stuff that was relevant to consumers of a
module went in that meta-argument page, but there was also a huge deep dive on
how the _author_ of a re-usable module should handle provider configurations
in cases where inheriting the default providers isn't sufficient. THAT, I
moved into a new page in the module development section. (For the consumer of
a module, this should all be an implementation detail; the module README
should tell you which aliased providers you need to configure and pass, and
then you just do it, without worrying about proxy configuration blocks etc.)
- The "standard module structure" recommendations in the main module development
page gets a page of its own, to make it more prominent and discoverable.
- Same deal with using the old URL as a landing page, at least for the main
module calls page. It didn't seem necessary for the module development page.
2020-11-12 21:21:35 -05:00
constraint; if no acceptable versions are installed, it will download the newest
version that meets the constraint.
Version constraints are supported only for modules installed from a module
2023-10-12 07:11:01 -04:00
registry, such as the [Public OpenTofu Registry](https://registry.opentofu.org/)
2024-07-29 05:06:30 -04:00
or any [TACOS](../../intro/tacos.mdx) (TF Automation and Collaboration Software) private modules registry.
website: Break up main Modules and Module Development pages
This one is a lot like the previous two commits, but slightly more complex:
- Only adding one new meta-argument page, for `providers`; otherwise, it just
re-uses the dual-purpose pages I made in the resources commit.
- About that `providers` argument: The stuff that was relevant to consumers of a
module went in that meta-argument page, but there was also a huge deep dive on
how the _author_ of a re-usable module should handle provider configurations
in cases where inheriting the default providers isn't sufficient. THAT, I
moved into a new page in the module development section. (For the consumer of
a module, this should all be an implementation detail; the module README
should tell you which aliased providers you need to configure and pass, and
then you just do it, without worrying about proxy configuration blocks etc.)
- The "standard module structure" recommendations in the main module development
page gets a page of its own, to make it more prominent and discoverable.
- Same deal with using the old URL as a landing page, at least for the main
module calls page. It didn't seem necessary for the module development page.
2020-11-12 21:21:35 -05:00
Other module sources can provide their own versioning mechanisms within the
source string itself, or might not support versions at all. In particular,
modules sourced from local file paths do not support `version`; since
they're loaded from the same source repository, they always share the same
version as their caller.
### Meta-arguments
2023-09-21 05:57:47 -04:00
Along with `source` and `version`, OpenTofu defines a few more
website: Break up main Modules and Module Development pages
This one is a lot like the previous two commits, but slightly more complex:
- Only adding one new meta-argument page, for `providers`; otherwise, it just
re-uses the dual-purpose pages I made in the resources commit.
- About that `providers` argument: The stuff that was relevant to consumers of a
module went in that meta-argument page, but there was also a huge deep dive on
how the _author_ of a re-usable module should handle provider configurations
in cases where inheriting the default providers isn't sufficient. THAT, I
moved into a new page in the module development section. (For the consumer of
a module, this should all be an implementation detail; the module README
should tell you which aliased providers you need to configure and pass, and
then you just do it, without worrying about proxy configuration blocks etc.)
- The "standard module structure" recommendations in the main module development
page gets a page of its own, to make it more prominent and discoverable.
- Same deal with using the old URL as a landing page, at least for the main
module calls page. It didn't seem necessary for the module development page.
2020-11-12 21:21:35 -05:00
optional meta-arguments that have special meaning across all modules,
described in more detail in the following pages:
- `count` - Creates multiple instances of a module from a single `module` block.
2024-04-24 07:24:30 -04:00
See [the `count` page](../../language/meta-arguments/count.mdx)
website: Break up main Modules and Module Development pages
This one is a lot like the previous two commits, but slightly more complex:
- Only adding one new meta-argument page, for `providers`; otherwise, it just
re-uses the dual-purpose pages I made in the resources commit.
- About that `providers` argument: The stuff that was relevant to consumers of a
module went in that meta-argument page, but there was also a huge deep dive on
how the _author_ of a re-usable module should handle provider configurations
in cases where inheriting the default providers isn't sufficient. THAT, I
moved into a new page in the module development section. (For the consumer of
a module, this should all be an implementation detail; the module README
should tell you which aliased providers you need to configure and pass, and
then you just do it, without worrying about proxy configuration blocks etc.)
- The "standard module structure" recommendations in the main module development
page gets a page of its own, to make it more prominent and discoverable.
- Same deal with using the old URL as a landing page, at least for the main
module calls page. It didn't seem necessary for the module development page.
2020-11-12 21:21:35 -05:00
for details.
- `for_each` - Creates multiple instances of a module from a single `module`
block. See
2024-04-24 07:24:30 -04:00
[the `for_each` page](../../language/meta-arguments/for_each.mdx)
website: Break up main Modules and Module Development pages
This one is a lot like the previous two commits, but slightly more complex:
- Only adding one new meta-argument page, for `providers`; otherwise, it just
re-uses the dual-purpose pages I made in the resources commit.
- About that `providers` argument: The stuff that was relevant to consumers of a
module went in that meta-argument page, but there was also a huge deep dive on
how the _author_ of a re-usable module should handle provider configurations
in cases where inheriting the default providers isn't sufficient. THAT, I
moved into a new page in the module development section. (For the consumer of
a module, this should all be an implementation detail; the module README
should tell you which aliased providers you need to configure and pass, and
then you just do it, without worrying about proxy configuration blocks etc.)
- The "standard module structure" recommendations in the main module development
page gets a page of its own, to make it more prominent and discoverable.
- Same deal with using the old URL as a landing page, at least for the main
module calls page. It didn't seem necessary for the module development page.
2020-11-12 21:21:35 -05:00
for details.
- `providers` - Passes provider configurations to a child module. See
2024-04-24 07:24:30 -04:00
[the `providers` page](../../language/meta-arguments/module-providers.mdx)
website: Break up main Modules and Module Development pages
This one is a lot like the previous two commits, but slightly more complex:
- Only adding one new meta-argument page, for `providers`; otherwise, it just
re-uses the dual-purpose pages I made in the resources commit.
- About that `providers` argument: The stuff that was relevant to consumers of a
module went in that meta-argument page, but there was also a huge deep dive on
how the _author_ of a re-usable module should handle provider configurations
in cases where inheriting the default providers isn't sufficient. THAT, I
moved into a new page in the module development section. (For the consumer of
a module, this should all be an implementation detail; the module README
should tell you which aliased providers you need to configure and pass, and
then you just do it, without worrying about proxy configuration blocks etc.)
- The "standard module structure" recommendations in the main module development
page gets a page of its own, to make it more prominent and discoverable.
- Same deal with using the old URL as a landing page, at least for the main
module calls page. It didn't seem necessary for the module development page.
2020-11-12 21:21:35 -05:00
for details. If not specified, the child module inherits all of the default
(un-aliased) provider configurations from the calling module.
- `depends_on` - Creates explicit dependencies between the entire
module and the listed targets. See
2024-04-24 07:24:30 -04:00
[the `depends_on` page](../../language/meta-arguments/depends_on.mdx)
website: Break up main Modules and Module Development pages
This one is a lot like the previous two commits, but slightly more complex:
- Only adding one new meta-argument page, for `providers`; otherwise, it just
re-uses the dual-purpose pages I made in the resources commit.
- About that `providers` argument: The stuff that was relevant to consumers of a
module went in that meta-argument page, but there was also a huge deep dive on
how the _author_ of a re-usable module should handle provider configurations
in cases where inheriting the default providers isn't sufficient. THAT, I
moved into a new page in the module development section. (For the consumer of
a module, this should all be an implementation detail; the module README
should tell you which aliased providers you need to configure and pass, and
then you just do it, without worrying about proxy configuration blocks etc.)
- The "standard module structure" recommendations in the main module development
page gets a page of its own, to make it more prominent and discoverable.
- Same deal with using the old URL as a landing page, at least for the main
module calls page. It didn't seem necessary for the module development page.
2020-11-12 21:21:35 -05:00
for details.
2025-10-16 14:26:48 -04:00
- `lifecycle` - Allows lifecycle customizations for modules, as described
in [Module Lifecycle](#module-lifecycle) below.
2025-10-16 12:10:00 -04:00
## Module Lifecycle
2025-10-16 14:26:48 -04:00
A `lifecycle` block inside a `module` block allows some customization of
OpenTofu's behavior relating to the overall module call, rather than to
individual resources inside the module.
2025-10-16 12:10:00 -04:00
```hcl
2025-10-16 14:26:48 -04:00
module "example" {
# ...normal module call arguments...
2025-10-16 12:10:00 -04:00
lifecycle {
2025-10-16 14:26:48 -04:00
# ...lifecycle arguments...
2025-10-16 12:10:00 -04:00
}
}
```
2025-10-16 14:26:48 -04:00
Module call lifecycle currently supports only a single argument:
* `enabled` (bool) - Controls whether the module call will be used by OpenTofu.
When set to `false`, the content of the module is excluded from the
configuration as if the call didn't exist. When set to `true` (the default),
the module operates normally.
For more information, refer to [the `enabled` meta-argument](../../language/meta-arguments/enabled.mdx).
website: Break up main Modules and Module Development pages
This one is a lot like the previous two commits, but slightly more complex:
- Only adding one new meta-argument page, for `providers`; otherwise, it just
re-uses the dual-purpose pages I made in the resources commit.
- About that `providers` argument: The stuff that was relevant to consumers of a
module went in that meta-argument page, but there was also a huge deep dive on
how the _author_ of a re-usable module should handle provider configurations
in cases where inheriting the default providers isn't sufficient. THAT, I
moved into a new page in the module development section. (For the consumer of
a module, this should all be an implementation detail; the module README
should tell you which aliased providers you need to configure and pass, and
then you just do it, without worrying about proxy configuration blocks etc.)
- The "standard module structure" recommendations in the main module development
page gets a page of its own, to make it more prominent and discoverable.
- Same deal with using the old URL as a landing page, at least for the main
module calls page. It didn't seem necessary for the module development page.
2020-11-12 21:21:35 -05:00
## Accessing Module Output Values
The resources defined in a module are encapsulated, so the calling module
cannot access their attributes directly. However, the child module can
2024-04-24 07:24:30 -04:00
declare [output values](../../language/values/outputs.mdx) to selectively
website: Break up main Modules and Module Development pages
This one is a lot like the previous two commits, but slightly more complex:
- Only adding one new meta-argument page, for `providers`; otherwise, it just
re-uses the dual-purpose pages I made in the resources commit.
- About that `providers` argument: The stuff that was relevant to consumers of a
module went in that meta-argument page, but there was also a huge deep dive on
how the _author_ of a re-usable module should handle provider configurations
in cases where inheriting the default providers isn't sufficient. THAT, I
moved into a new page in the module development section. (For the consumer of
a module, this should all be an implementation detail; the module README
should tell you which aliased providers you need to configure and pass, and
then you just do it, without worrying about proxy configuration blocks etc.)
- The "standard module structure" recommendations in the main module development
page gets a page of its own, to make it more prominent and discoverable.
- Same deal with using the old URL as a landing page, at least for the main
module calls page. It didn't seem necessary for the module development page.
2020-11-12 21:21:35 -05:00
export certain values to be accessed by the calling module.
For example, if the `./app-cluster` module referenced in the example above
exported an output value named `instance_ids` then the calling module
can reference that result using the expression `module.servers.instance_ids`:
```hcl
resource "aws_elb" "example" {
# ...
instances = module.servers.instance_ids
}
```
For more information about referring to named values, see
2024-04-24 07:24:30 -04:00
[Expressions](../../language/expressions/index.mdx).
website: Break up main Modules and Module Development pages
This one is a lot like the previous two commits, but slightly more complex:
- Only adding one new meta-argument page, for `providers`; otherwise, it just
re-uses the dual-purpose pages I made in the resources commit.
- About that `providers` argument: The stuff that was relevant to consumers of a
module went in that meta-argument page, but there was also a huge deep dive on
how the _author_ of a re-usable module should handle provider configurations
in cases where inheriting the default providers isn't sufficient. THAT, I
moved into a new page in the module development section. (For the consumer of
a module, this should all be an implementation detail; the module README
should tell you which aliased providers you need to configure and pass, and
then you just do it, without worrying about proxy configuration blocks etc.)
- The "standard module structure" recommendations in the main module development
page gets a page of its own, to make it more prominent and discoverable.
- Same deal with using the old URL as a landing page, at least for the main
module calls page. It didn't seem necessary for the module development page.
2020-11-12 21:21:35 -05:00
## Transferring Resource State Into Modules
2021-07-08 19:58:26 -04:00
Moving `resource` blocks from one module into several child modules causes
2023-09-21 05:57:47 -04:00
OpenTofu to see the new location as an entirely different resource. As a
result, OpenTofu plans to destroy all resource instances at the old address
2021-07-08 19:58:26 -04:00
and create new instances at the new address.
To preserve existing objects, you can use
2024-04-24 07:24:30 -04:00
[refactoring blocks](../../language/modules/develop/refactoring.mdx) to record the old and new
2023-09-21 05:57:47 -04:00
addresses for each resource instance. This directs OpenTofu to treat existing
2021-07-08 19:58:26 -04:00
objects at the old addresses as if they had originally been created at the
corresponding new addresses.
## Replacing resources within a module
You may have an object that needs to be replaced with a new object for a reason
2023-09-21 05:57:47 -04:00
that isn't automatically visible to OpenTofu, such as if a particular virtual
2021-07-08 19:58:26 -04:00
machine is running on degraded underlying hardware. In this case, you can use
2024-04-24 07:24:30 -04:00
[the `-replace=...` planning option](../../cli/commands/plan.mdx#replace-address)
2023-09-21 05:57:47 -04:00
to force OpenTofu to propose replacing that object.
2021-07-08 19:58:26 -04:00
If the object belongs to a resource within a nested module, specify the full
path to that resource including all of the nested module steps leading to it.
For example:
```shellsession
2023-09-21 05:57:47 -04:00
$ tofu plan -replace=module.example.aws_instance.example
website: Break up main Modules and Module Development pages
This one is a lot like the previous two commits, but slightly more complex:
- Only adding one new meta-argument page, for `providers`; otherwise, it just
re-uses the dual-purpose pages I made in the resources commit.
- About that `providers` argument: The stuff that was relevant to consumers of a
module went in that meta-argument page, but there was also a huge deep dive on
how the _author_ of a re-usable module should handle provider configurations
in cases where inheriting the default providers isn't sufficient. THAT, I
moved into a new page in the module development section. (For the consumer of
a module, this should all be an implementation detail; the module README
should tell you which aliased providers you need to configure and pass, and
then you just do it, without worrying about proxy configuration blocks etc.)
- The "standard module structure" recommendations in the main module development
page gets a page of its own, to make it more prominent and discoverable.
- Same deal with using the old URL as a landing page, at least for the main
module calls page. It didn't seem necessary for the module development page.
2020-11-12 21:21:35 -05:00
```
2021-07-08 19:58:26 -04:00
The above selects a `resource "aws_instance" "example"` declared inside a
`module "example"` child module declared inside your root module.
2023-09-21 05:57:47 -04:00
Because replacing is a very disruptive action, OpenTofu only allows selecting
2021-07-08 19:58:26 -04:00
individual resource instances. There is no syntax to force replacing _all_
resource instances belonging to a particular module.
2025-04-25 06:29:42 -04:00
## Removing a module
The same as any `resource`, a `module` can be removed as well by using the `removed` refactoring block.
When you remove the configuration of a module, OpenTofu will destroy all the resources that the removed module was managing.
There are cases when the module is wanted to be removed from the configuration (and from the state) but the resources managed by it should stay untouched.
To achieve this, follow these steps:
1. Delete the module from your configuration.
2. Add a removed block instead, specifying the module address you want to "forget" in the `from` attribute.
3. Specify the `lifecycle.destroy = false`
```hcl
removed {
from = module.some_module
lifecycle {
destroy = false
}
}
```
:::note
In contrast with `resource` blocks removal, `removed` blocks pointing to modules, do not allow usage of `provisioners`.
2025-10-16 12:10:00 -04:00
:::
