Merge pull request #26953 from hashicorp/nov20_backport_breakup_etc

Website: Backport breakup of expressions, resources, and modules pages

website/docs/cli/code/index.html.md

@@ -15,7 +15,7 @@ potentially save you time and effort.
 
 - [The `terraform console` command](/docs/commands/console.html) starts an
  interactive shell for evaluating Terraform
- [expressions](/docs/configuration/expressions.html), which can be a faster way
+ [expressions](/docs/configuration/expressions/index.html), which can be a faster way
  to verify that a particular resource argument results in the value you expect.
 
 

website/docs/commands/0.12upgrade.html.markdown

@@ -71,7 +71,7 @@ the change.
 Once upgraded the configuration will no longer be compatible with Terraform
 v0.11 and earlier. When upgrading a shared module that is called from multiple
 configurations, you may need to
-[fix existing configurations to a previous version](/docs/configuration/modules.html#module-versions)
+[fix existing configurations to a previous version](/docs/configuration/blocks/modules/syntax.html#version)
 to allow for a gradual upgrade. If the module is published via
 [a Terraform registry](/docs/registry/), assign a new _major_ version number
 to the upgraded module source to represent the fact that this is a breaking

website/docs/commands/console.html.markdown

@@ -10,14 +10,14 @@ description: |-
 # Command: console
 
 The `terraform console` command provides an interactive console for
-evaluating [expressions](/docs/configuration/expressions.html).
+evaluating [expressions](/docs/configuration/expressions/index.html).
 
 ## Usage
 
 Usage: `terraform console [options]`
 
 This command provides an interactive command-line console for evaluating and
-experimenting with [expressions](/docs/configuration/expressions.html).
+experimenting with [expressions](/docs/configuration/expressions/index.html).
 This is useful for testing interpolations before using them in configurations,
 and for interacting with any values currently saved in
 [state](/docs/state/index.html).

website/docs/commands/import.html.md

@@ -133,7 +133,7 @@ $ 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):
+[`count`](/docs/configuration/meta-arguments/count.html):
 
 ```shell
 $ terraform import 'aws_instance.baz[0]' i-abcd1234
@@ -142,7 +142,7 @@ $ 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):
+[`for_each`](/docs/configuration/meta-arguments/for_each.html):
 
 Linux, Mac OS, and UNIX:
 

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

@@ -95,7 +95,7 @@ $ terraform state mv -state-out=other.tfstate 'module.app' 'module.app'
 ## 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
+[`count`](/docs/configuration/meta-arguments/count.html) to
 the first instance of a resource named `helper` also configured with `count`:
 
 ```shell
@@ -105,7 +105,7 @@ $ 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)
+[`for_each`](/docs/configuration/meta-arguments/for_each.html)
 to the `"example456"` instance of a resource named `helper` also configuring `for_each`:
 
 Linux, Mac OS, and UNIX:

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

@@ -78,7 +78,7 @@ $ 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):
+[`count`](/docs/configuration/meta-arguments/count.html):
 
 ```shell
 $ terraform state rm 'packet_device.worker[0]'
@@ -87,7 +87,7 @@ $ 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):
+[`for_each`](/docs/configuration/meta-arguments/for_each.html):
 
 Linux, Mac OS, and UNIX:
 

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

@@ -61,7 +61,7 @@ $ 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):
+[`count`](/docs/configuration/meta-arguments/count.html):
 
 ```shell
 $ terraform state show 'packet_device.worker[0]'
@@ -70,7 +70,7 @@ $ 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):
+[`for_each`](/docs/configuration/meta-arguments/for_each.html):
 
 Linux, Mac OS, and UNIX:
 

website/docs/configuration-0-11/interpolation.html.md

@@ -10,7 +10,7 @@ description: |-
 
 -> **Note:** This page is about Terraform 0.11 and earlier. For Terraform 0.12
 and later, see
-[Configuration Language: Expressions](../configuration/expressions.html) and
+[Configuration Language: Expressions](/docs/configuration/expressions/index.html) and
 [Configuration Language: Functions](../configuration/functions.html).
 
 Embedded within strings in Terraform, whether you're using the

website/docs/configuration/attr-as-blocks.html.md

@@ -153,7 +153,7 @@ example = [
 
 For the arguments that use the attributes-as-blocks usage mode, the above is
 a better pattern than using
-[`dynamic` blocks](/docs/configuration/expressions.html#dynamic-blocks)
+[`dynamic` blocks](/docs/configuration/expressions/dynamic-blocks.html)
 because the case where the
 caller provides an empty list will result in explicitly assigning an empty
 list value, rather than assigning no value at all and thus retaining and

website/docs/configuration/blocks/modules/index.html.md

@@ -48,12 +48,20 @@ module registry for sharing modules internally within your organization.
 
 ## Using Modules
 
-- [Module Blocks](/docs/configuration/modules.html) documents the syntax for
+- [Module Blocks](/docs/configuration/blocks/modules/syntax.html) documents the syntax for
  calling a child module from a parent module, including meta-arguments like
  `for_each`.
+
 - [Module Sources](/docs/modules/sources.html) documents what kinds of paths,
  addresses, and URIs can be used in the `source` argument of a module block.
 
+- The Meta-Arguments section documents special arguments that can be used with
+ every module, including
+ [`providers`](/docs/configuration/meta-arguments/module-providers.html),
+ [`depends_on`](/docs/configuration/meta-arguments/depends_on.html),
+ [`count`](/docs/configuration/meta-arguments/count.html),
+ and [`for_each`](/docs/configuration/meta-arguments/for_each.html).
+
 ## Developing Modules
 
 For information about developing reusable modules, see

website/docs/configuration/blocks/modules/syntax.html.md

@@ -0,0 +1,201 @@
+---
+layout: "language"
+page_title: "Modules - Configuration Language"
+sidebar_current: "docs-config-modules"
+description: |-
+ Modules allow multiple resources to be grouped together and encapsulated.
+---
+
+# Module Blocks
+
+-> **Note:** This page is about Terraform 0.12 and later. For Terraform 0.11 and
+earlier, see
+[0.11 Configuration Language: Modules](../configuration-0-11/modules.html).
+
+> **Hands-on:** Try the [Reuse Configuration with Modules](https://learn.hashicorp.com/collections/terraform/modules?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) collection on HashiCorp Learn.
+
+A _module_ is a container for multiple resources that are used together.
+
+Every Terraform configuration has at least one module, known as its
+_root module_, which consists of the resources defined in the `.tf` files in
+the main working directory.
+
+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
+about creating re-usable child modules, see [Module Development](/docs/modules/index.html).
+
+## Calling a Child Module
+
+To _call_ a module means to include the contents of that module into the
+configuration with specific values for its
+[input variables](/docs/configuration/variables.html). Modules are called
+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.
+
+- Most other arguments correspond to [input variables](/docs/configuration/variables.html)
+ defined by the module. (The `servers` argument in the example above is one of
+ these.)
+
+- Terraform defines a few other meta-arguments that can be used with all
+ modules, including `for_each` and `depends_on`.
+
+### Source
+
+All modules **require** a `source` argument, which is a meta-argument defined by
+Terraform. Its value is either the path to a local directory containing the
+module's configuration files, or a remote module source that Terraform should
+download and use. This value must be a literal string with no template
+sequences; arbitrary expressions are not allowed. For more information on
+possible values for this argument, see [Module Sources](/docs/modules/sources.html).
+
+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
+`terraform init` to allow Terraform the opportunity to adjust the installed
+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
+}
+```
+
+The `version` argument accepts a [version constraint string](/docs/configuration/version-constraints.html).
+Terraform will use the newest installed version of the module that meets the
+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
+registry, such as the public [Terraform Registry](https://registry.terraform.io/)
+or [Terraform Cloud's private module registry](/docs/cloud/registry/index.html).
+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
+
+Along with `source` and `version`, Terraform defines a few more
+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.
+ See [the `count` page](/docs/configuration/meta-arguments/count.html)
+ for details.
+
+- `for_each` - Creates multiple instances of a module from a single `module`
+ block. See
+ [the `for_each` page](/docs/configuration/meta-arguments/for_each.html)
+ for details.
+
+- `providers` - Passes provider configurations to a child module. See
+ [the `providers` page](/docs/configuration/meta-arguments/module-providers.html)
+ 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
+ [the `depends_on` page](/docs/configuration/meta-arguments/depends_on.html)
+ for details.
+
+In addition to the above, the `lifecycle` argument is not currently used by
+Terraform but is reserved for planned future features.
+
+## 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
+declare [output values](/docs/configuration/outputs.html) to selectively
+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
+[Expressions](/docs/configuration/expressions/index.html).
+
+## Transferring Resource State Into Modules
+
+When refactoring an existing configuration to split code into child modules,
+moving resource blocks between modules causes Terraform to see the new location
+as an entirely different resource from the old. Always check the execution plan
+after moving code across modules to ensure that no resources are deleted by
+surprise.
+
+If you want to make sure an existing resource is preserved, use
+[the `terraform state mv` command](/docs/commands/state/mv.html) to inform
+Terraform that it has moved to a different module.
+
+When passing resource addresses to `terraform state mv`, resources within child
+modules must be prefixed with `module.<MODULE NAME>.`. If a module was called with
+[`count`](/docs/configuration/meta-arguments/count.html) or
+[`for_each`](/docs/configuration/meta-arguments/for_each.html),
+its resource addresses must be prefixed with `module.<MODULE NAME>[<INDEX>].`
+instead, where `<INDEX>` matches the `count.index` or `each.key` value of a
+particular module instance.
+
+Full resource addresses for module contents are used within the UI and on the
+command line, but cannot be used within a Terraform configuration. Only
+[outputs](/docs/configuration/outputs.html) from a module can be referenced from
+elsewhere in your configuration.
+
+## Tainting resources within a module
+
+The [taint command](/docs/commands/taint.html) can be used to _taint_ specific
+resources within a module:
+
+```shell
+$ terraform taint module.salt_master.aws_instance.salt_master
+```
+
+It is not possible to taint an entire module. Instead, each resource within
+the module must be tainted separately.

website/docs/configuration/blocks/providers/index.html.md

@@ -13,7 +13,7 @@ configuration (like endpoint URLs or cloud regions) before they can be used.
 
 ## What Providers Do
 
-Each provider adds a set of [resource types](/docs/configuration/resources.html)
+Each provider adds a set of [resource types](/docs/configuration/blocks/resources/index.html)
 and/or [data sources](/docs/configuration/data-sources.html) that Terraform can
 manage.