mirror of
https://github.com/opentffoundation/opentf.git
synced 2025-12-25 01:00:16 -05:00
migrate docs to mdx
This commit is contained in:
Dylan Staley
@@ -1,7 +1,5 @@
|
||||
---
|
||||
layout: "language"
|
||||
page_title: "Module Composition"
|
||||
sidebar_current: "docs-modules-composition"
|
||||
page_title: Module Composition
|
||||
description: |-
|
||||
Module composition allows infrastructure to be described from modular
|
||||
building blocks.
|
||||
@@ -310,7 +308,7 @@ Most modules contain `resource` blocks and thus describe infrastructure to be
|
||||
created and managed. It may sometimes be useful to write modules that do not
|
||||
describe any new infrastructure at all, but merely retrieve information about
|
||||
existing infrastructure that was created elsewhere using
|
||||
[data sources](/docs/language/data-sources/index.html).
|
||||
[data sources](/language/data-sources).
|
||||
|
||||
As with conventional modules, we suggest using this technique only when the
|
||||
module raises the level of abstraction in some way, in this case by
|
||||
@@ -346,7 +344,7 @@ data sources, or it could read saved information from a Consul cluster using
|
||||
[`consul_keys`](https://registry.terraform.io/providers/hashicorp/consul/latest/docs/data-sources/keys),
|
||||
or it might read the outputs directly from the state of the configuration that
|
||||
manages the network using
|
||||
[`terraform_remote_state`](https://www.terraform.io/docs/language/state/remote-state-data.html).
|
||||
[`terraform_remote_state`](/language/state/remote-state-data).
|
||||
|
||||
The key benefit of this approach is that the source of this information can
|
||||
change over time without updating every configuration that depends on it.
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
layout: "language"
|
||||
page_title: "Creating Modules"
|
||||
sidebar_current: "docs-modules"
|
||||
description: "Modules are containers for multiple resources that are used together in a configuration. Learn when to create modules and about module structure."
|
||||
page_title: Creating Modules
|
||||
description: >-
|
||||
Modules are containers for multiple resources that are used together in a
|
||||
configuration. Learn when to create modules and about module structure.
|
||||
---
|
||||
|
||||
# Creating Modules
|
||||
@@ -14,27 +14,27 @@ Modules can be used to create lightweight abstractions, so that you can
|
||||
describe your infrastructure in terms of its architecture, rather than
|
||||
directly in terms of physical objects.
|
||||
|
||||
The `.tf` files in your working directory when you run [`terraform plan`](/docs/cli/commands/plan.html)
|
||||
or [`terraform apply`](/docs/cli/commands/apply.html) together form the _root_
|
||||
module. That module may [call other modules](/docs/language/modules/syntax.html#calling-a-child-module)
|
||||
The `.tf` files in your working directory when you run [`terraform plan`](/cli/commands/plan)
|
||||
or [`terraform apply`](/cli/commands/apply) together form the _root_
|
||||
module. That module may [call other modules](/language/modules/syntax#calling-a-child-module)
|
||||
and connect them together by passing output values from one to input values
|
||||
of another.
|
||||
|
||||
To learn how to _use_ modules, see [the Modules configuration section](/docs/language/modules/index.html).
|
||||
To learn how to _use_ modules, see [the Modules configuration section](/language/modules).
|
||||
This section is about _creating_ re-usable modules that other configurations
|
||||
can include using `module` blocks.
|
||||
|
||||
## Module structure
|
||||
|
||||
Re-usable modules are defined using all of the same
|
||||
[configuration language](/docs/language/index.html) concepts we use in root modules.
|
||||
[configuration language](/language) concepts we use in root modules.
|
||||
Most commonly, modules use:
|
||||
|
||||
* [Input variables](/docs/language/values/variables.html) to accept values from
|
||||
* [Input variables](/language/values/variables) to accept values from
|
||||
the calling module.
|
||||
* [Output values](/docs/language/values/outputs.html) to return results to the
|
||||
* [Output values](/language/values/outputs) to return results to the
|
||||
calling module, which it can then use to populate arguments elsewhere.
|
||||
* [Resources](/docs/language/resources/index.html) to define one or more
|
||||
* [Resources](/language/resources) to define one or more
|
||||
infrastructure objects that the module will manage.
|
||||
|
||||
To define a module, create a new directory for it and place one or more `.tf`
|
||||
@@ -44,7 +44,7 @@ be re-used by lots of configurations you may wish to place it in its own
|
||||
version control repository.
|
||||
|
||||
Modules can also call other modules using a `module` block, but we recommend
|
||||
keeping the module tree relatively flat and using [module composition](./composition.html)
|
||||
keeping the module tree relatively flat and using [module composition](/language/modules/develop/composition)
|
||||
as an alternative to a deeply-nested tree of modules, because this makes
|
||||
the individual modules easier to re-use in different combinations.
|
||||
|
||||
@@ -72,7 +72,7 @@ calling module instead.
|
||||
|
||||
## Refactoring module resources
|
||||
|
||||
You can include [refactoring blocks](refactoring.html) to record how resource
|
||||
You can include [refactoring blocks](/language/modules/develop/refactoring) to record how resource
|
||||
names and module structure have changed from previous module versions.
|
||||
Terraform uses that information during planning to reinterpret existing objects
|
||||
as if they had been created at the corresponding new addresses, eliminating a
|
||||
@@ -1,6 +1,5 @@
|
||||
---
|
||||
layout: "language"
|
||||
page_title: "Providers Within Modules - Configuration Language"
|
||||
page_title: Providers Within Modules - Configuration Language
|
||||
---
|
||||
|
||||
# Providers Within Modules
|
||||
@@ -45,10 +44,10 @@ to reintroduce the provider configuration.
|
||||
## Provider Version Constraints in Modules
|
||||
|
||||
Although provider _configurations_ are shared between modules, each module must
|
||||
declare its own [provider requirements](/docs/language/providers/requirements.html), so that
|
||||
declare its own [provider requirements](/language/providers/requirements), so that
|
||||
Terraform can ensure that there is a single version of the provider that is
|
||||
compatible with all modules in the configuration and to specify the
|
||||
[source address](/docs/language/providers/requirements.html#source-addresses) that serves as
|
||||
[source address](/language/providers/requirements#source-addresses) that serves as
|
||||
the global (module-agnostic) identifier for a provider.
|
||||
|
||||
To declare that a module requires particular versions of a specific provider,
|
||||
@@ -71,7 +70,7 @@ however, specify any of the configuration settings that determine what remote
|
||||
endpoints the provider will access, such as an AWS region; configuration
|
||||
settings come from provider _configurations_, and a particular overall Terraform
|
||||
configuration can potentially have
|
||||
[several different configurations for the same provider](/docs/language/providers/configuration.html#alias-multiple-provider-configurations).
|
||||
[several different configurations for the same provider](/language/providers/configuration#alias-multiple-provider-configurations).
|
||||
|
||||
## Provider Aliases Within Modules
|
||||
|
||||
@@ -133,10 +132,10 @@ resource "aws_s3_bucket" "example" {
|
||||
We recommend using this approach when a single configuration for each provider
|
||||
is sufficient for an entire configuration.
|
||||
|
||||
~> **Note:** Only provider configurations are inherited by child modules, not provider source or version requirements. Each module must [declare its own provider requirements](/docs/language/providers/requirements.html). This is especially important for non-HashiCorp providers.
|
||||
~> **Note:** Only provider configurations are inherited by child modules, not provider source or version requirements. Each module must [declare its own provider requirements](/language/providers/requirements). This is especially important for non-HashiCorp providers.
|
||||
|
||||
In more complex situations there may be
|
||||
[multiple provider configurations](/docs/language/providers/configuration.html#alias-multiple-provider-configurations),
|
||||
[multiple provider configurations](/language/providers/configuration#alias-multiple-provider-configurations),
|
||||
or a child module may need to use different provider settings than
|
||||
its parent. For such situations, you must pass providers explicitly.
|
||||
|
||||
@@ -173,7 +172,7 @@ module "example" {
|
||||
```
|
||||
|
||||
The `providers` argument within a `module` block is similar to
|
||||
[the `provider` argument](/docs/language/meta-arguments/resource-provider.html)
|
||||
[the `provider` argument](/language/meta-arguments/resource-provider)
|
||||
within a resource, but is a map rather than a single string because a module may
|
||||
contain resources from many different providers.
|
||||
|
||||
@@ -1,20 +1,17 @@
|
||||
---
|
||||
layout: "language"
|
||||
page_title: "Publishing Modules"
|
||||
sidebar_current: "docs-modules-publish"
|
||||
description: |-
|
||||
A module is a container for multiple resources that are used together.
|
||||
page_title: Publishing Modules
|
||||
description: A module is a container for multiple resources that are used together.
|
||||
---
|
||||
|
||||
# Publishing Modules
|
||||
|
||||
If you've built a module that you intend to be reused, we recommend
|
||||
[publishing the module](/docs/registry/modules/publish.html) on the
|
||||
[publishing the module](/registry/modules/publish) on the
|
||||
[Terraform Registry](https://registry.terraform.io). This will version
|
||||
your module, generate documentation, and more.
|
||||
|
||||
Published modules can be easily consumed by Terraform, and users can
|
||||
[constrain module versions](/docs/language/modules/syntax.html#version)
|
||||
[constrain module versions](/language/modules/syntax#version)
|
||||
for safe and predictable updates. The following example shows how a caller
|
||||
might use a module from the Terraform Registry:
|
||||
|
||||
@@ -25,21 +22,20 @@ module "consul" {
|
||||
```
|
||||
|
||||
If you do not wish to publish your modules in the public registry, you can
|
||||
instead use a [private registry](/docs/registry/private.html) to get
|
||||
instead use a [private registry](/registry/private) to get
|
||||
the same benefits.
|
||||
|
||||
We welcome contributions of Terraform modules from our community members, partners, and customers. Our ecosystem is made richer by each new module created or an existing one updated, as they reflect the wide range of experience and technical requirements of the community that uses them. Our cloud provider partners often seek to develop specific modules for popular or challenging use cases on their platform and utilize them as valuable learning experiences to empathize with their users. Similarly, our community module developers incorporate a variety of opinions and use cases from the broader Terraform community. Both types of modules have their place in the Terraform registry, accessible to practitioners who can decide which modules best fit their requirements.
|
||||
|
||||
|
||||
## Distribution via other sources
|
||||
|
||||
Although the registry is the native mechanism for distributing re-usable
|
||||
modules, Terraform can also install modules from
|
||||
[various other sources](/docs/language/modules/sources.html). The alternative sources
|
||||
[various other sources](/language/modules/sources). The alternative sources
|
||||
do not support the first-class versioning mechanism, but some sources have
|
||||
their own mechanisms for selecting particular VCS commits, etc.
|
||||
|
||||
We recommend that modules distributed via other protocols still use the
|
||||
[standard module structure](/docs/language/modules/develop/structure.html) so that they can
|
||||
[standard module structure](/language/modules/develop/structure) so that they can
|
||||
be used in a similar way as a registry module or be published on the registry
|
||||
at a later time.
|
||||
@@ -1,15 +1,12 @@
|
||||
---
|
||||
layout: "language"
|
||||
page_title: "Refactoring"
|
||||
sidebar_current: "docs-modules-recactoring"
|
||||
description: |-
|
||||
How to make backward-compatible changes to modules already in use.
|
||||
page_title: Refactoring
|
||||
description: How to make backward-compatible changes to modules already in use.
|
||||
---
|
||||
|
||||
# Refactoring
|
||||
|
||||
-> **Note:** Explicit refactoring declarations with `moved` blocks is available in Terraform v1.1 and later. For earlier Terraform versions or for refactoring actions too complex to express as `moved` blocks, you can
|
||||
use the [`terraform state mv` CLI command](/docs/cli/commands/state/mv.html)
|
||||
use the [`terraform state mv` CLI command](/cli/commands/state/mv)
|
||||
as a separate step.
|
||||
|
||||
In shared modules and long-lived configurations, you may eventually outgrow
|
||||
@@ -125,7 +122,7 @@ resource "aws_instance" "a" {
|
||||
Applying this configuration would lead to Terraform creating an object
|
||||
bound to the address `aws_instance.a`.
|
||||
|
||||
Later, you use [`for_each`](../../meta-arguments/for_each.html) with this
|
||||
Later, you use [`for_each`](/language/meta-arguments/for_each) with this
|
||||
resource to systematically declare multiple instances. To preserve an object
|
||||
that was previously associated with `aws_instance.a` alone, you must add a
|
||||
`moved` block to specify which instance key the object will take in the new
|
||||
@@ -264,7 +261,7 @@ Applying this configuration would cause Terraform to create objects whose
|
||||
addresses begin with `module.a`.
|
||||
|
||||
In later module versions, you may need to use
|
||||
[`count`](../../meta-arguments/count.html) with this resource to systematically
|
||||
[`count`](/language/meta-arguments/count) with this resource to systematically
|
||||
declare multiple instances. To preserve an object that was previously associated
|
||||
with `aws_instance.a` alone, you can add a `moved` block to specify which
|
||||
instance key that object will take in the new configuration:
|
||||
@@ -328,8 +325,8 @@ To achieve this refactoring without replacing existing objects bound to the
|
||||
old resource addresses, you must:
|
||||
|
||||
1. Write module "x", copying over the two resources it should contain.
|
||||
2. Write module "y", copying over the one resource it should contain.
|
||||
3. Edit the original module to no longer include any of these resources, and
|
||||
1. Write module "y", copying over the one resource it should contain.
|
||||
1. Edit the original module to no longer include any of these resources, and
|
||||
instead to contain only shim configuration to migrate existing users.
|
||||
|
||||
The new modules "x" and "y" should contain only `resource` blocks:
|
||||
@@ -401,13 +398,13 @@ typical rule that a parent module sees its child module as a "closed box",
|
||||
unaware of exactly which resources are declared inside it. This compromise
|
||||
assumes that all three of these modules are maintained by the same people
|
||||
and distributed together in a single
|
||||
[module package](../sources.html#modules-in-package-sub-directories).
|
||||
[module package](/language/modules/sources#modules-in-package-sub-directories).
|
||||
|
||||
To reduce [coupling](https://en.wikipedia.org/wiki/Coupling_(computer_programming))
|
||||
To reduce [coupling](https://en.wikipedia.org/wiki/Coupling_\(computer_programming\))
|
||||
between separately-packaged modules, Terraform only allows declarations of
|
||||
moves between modules in the same package. In other words, Terraform would
|
||||
not have allowed moving into `module.x` above if the `source` address of
|
||||
that call had not been a [local path](../sources.html#local-paths).
|
||||
that call had not been a [local path](/language/modules/sources#local-paths).
|
||||
|
||||
Terraform resolves module references in `moved` blocks relative to the module
|
||||
instance they are defined in. For example, if the original module above were
|
||||
@@ -439,7 +436,6 @@ If you do decide to remove `moved` blocks, proceed with caution. It can be safe
|
||||
If you need to rename or move the same object twice, we recommend documenting the full history
|
||||
using _chained_ `moved` blocks, where the new block refers to the existing block:
|
||||
|
||||
|
||||
```hcl
|
||||
moved {
|
||||
from = aws_instance.a
|
||||
@@ -1,6 +1,5 @@
|
||||
---
|
||||
layout: "language"
|
||||
page_title: "Standard Module Structure"
|
||||
page_title: Standard Module Structure
|
||||
---
|
||||
|
||||
# Standard Module Structure
|
||||
@@ -54,8 +53,8 @@ don't need to do any extra work to follow the standard structure.
|
||||
* **Variables and outputs should have descriptions.** All variables and
|
||||
outputs should have one or two sentence descriptions that explain their
|
||||
purpose. This is used for documentation. See the documentation for
|
||||
[variable configuration](/docs/language/values/variables.html) and
|
||||
[output configuration](/docs/language/values/outputs.html) for more details.
|
||||
[variable configuration](/language/values/variables) and
|
||||
[output configuration](/language/values/outputs) for more details.
|
||||
|
||||
* **Nested modules**. Nested modules should exist under the `modules/`
|
||||
subdirectory. Any nested module with a `README.md` is considered usable
|
||||
@@ -75,7 +74,7 @@ don't need to do any extra work to follow the standard structure.
|
||||
again separately.
|
||||
|
||||
If a repository or package contains multiple nested modules, they should
|
||||
ideally be [composable](./composition.html) by the caller, rather than
|
||||
ideally be [composable](/language/modules/develop/composition) by the caller, rather than
|
||||
calling directly to each other and creating a deeply-nested tree of modules.
|
||||
|
||||
* **Examples**. Examples of using the module should exist under the
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
layout: "language"
|
||||
page_title: "Modules Overview - Configuration Language"
|
||||
description: "Modules are containers for multiple resources that are used together in a configuration. Find resources for using, developing, and publishing modules."
|
||||
page_title: Modules Overview - Configuration Language
|
||||
description: >-
|
||||
Modules are containers for multiple resources that are used together in a
|
||||
configuration. Find resources for using, developing, and publishing modules.
|
||||
---
|
||||
|
||||
# Modules
|
||||
@@ -43,27 +44,27 @@ download them automatically if you specify the appropriate source and version in
|
||||
a module call block.
|
||||
|
||||
Also, members of your organization might produce modules specifically crafted
|
||||
for your own infrastructure needs. [Terraform Cloud](/docs/cloud/index.html) and
|
||||
[Terraform Enterprise](/docs/enterprise/index.html) both include a private
|
||||
for your own infrastructure needs. [Terraform Cloud](/cloud) and
|
||||
[Terraform Enterprise](/enterprise) both include a private
|
||||
module registry for sharing modules internally within your organization.
|
||||
|
||||
## Using Modules
|
||||
|
||||
- [Module Blocks](/docs/language/modules/syntax.html) documents the syntax for
|
||||
- [Module Blocks](/language/modules/syntax) documents the syntax for
|
||||
calling a child module from a parent module, including meta-arguments like
|
||||
`for_each`.
|
||||
|
||||
- [Module Sources](/docs/language/modules/sources.html) documents what kinds of paths,
|
||||
- [Module Sources](/language/modules/sources) 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/language/meta-arguments/module-providers.html),
|
||||
[`depends_on`](/docs/language/meta-arguments/depends_on.html),
|
||||
[`count`](/docs/language/meta-arguments/count.html),
|
||||
and [`for_each`](/docs/language/meta-arguments/for_each.html).
|
||||
[`providers`](/language/meta-arguments/module-providers),
|
||||
[`depends_on`](/language/meta-arguments/depends_on),
|
||||
[`count`](/language/meta-arguments/count),
|
||||
and [`for_each`](/language/meta-arguments/for_each).
|
||||
|
||||
## Developing Modules
|
||||
|
||||
For information about developing reusable modules, see
|
||||
[Module Development](/docs/language/modules/develop/index.html).
|
||||
[Module Development](/language/modules/develop).
|
||||
@@ -1,13 +1,14 @@
|
||||
---
|
||||
layout: "language"
|
||||
page_title: "Module Sources"
|
||||
sidebar_current: "docs-modules-sources"
|
||||
description: "The source argument tells Terraform where to find child modules's configurations in locations like GitHub, the Terraform Registry, Bitbucket, Git, Mercurial, S3, and GCS."
|
||||
page_title: Module Sources
|
||||
description: >-
|
||||
The source argument tells Terraform where to find child modules's
|
||||
configurations in locations like GitHub, the Terraform Registry, Bitbucket,
|
||||
Git, Mercurial, S3, and GCS.
|
||||
---
|
||||
|
||||
# Module Sources
|
||||
|
||||
The `source` argument in [a `module` block](/docs/language/modules/syntax.html)
|
||||
The `source` argument in [a `module` block](/language/modules/syntax)
|
||||
tells Terraform where to find the source code for the desired child module.
|
||||
|
||||
Terraform uses this during the module installation step of `terraform init`
|
||||
@@ -16,28 +17,28 @@ used by other Terraform commands.
|
||||
|
||||
> **Hands-on:** Try our HashiCorp Learn tutorials to use modules from [the
|
||||
> registry](https://learn.hashicorp.com/tutorials/terraform/module-use)
|
||||
>or [locally](https://learn.hashicorp.com/tutorials/terraform/module-create).
|
||||
> or [locally](https://learn.hashicorp.com/tutorials/terraform/module-create).
|
||||
|
||||
The module installer supports installation from a number of different source
|
||||
types, as listed below.
|
||||
|
||||
* [Local paths](#local-paths)
|
||||
* [Local paths](#local-paths)
|
||||
|
||||
* [Terraform Registry](#terraform-registry)
|
||||
* [Terraform Registry](#terraform-registry)
|
||||
|
||||
* [GitHub](#github)
|
||||
* [GitHub](#github)
|
||||
|
||||
* [Bitbucket](#bitbucket)
|
||||
* [Bitbucket](#bitbucket)
|
||||
|
||||
* Generic [Git](#generic-git-repository), [Mercurial](#generic-mercurial-repository) repositories
|
||||
* Generic [Git](#generic-git-repository), [Mercurial](#generic-mercurial-repository) repositories
|
||||
|
||||
* [HTTP URLs](#http-urls)
|
||||
* [HTTP URLs](#http-urls)
|
||||
|
||||
* [S3 buckets](#s3-bucket)
|
||||
* [S3 buckets](#s3-bucket)
|
||||
|
||||
* [GCS buckets](#gcs-bucket)
|
||||
* [GCS buckets](#gcs-bucket)
|
||||
|
||||
* [Modules in Package Sub-directories](#modules-in-package-sub-directories)
|
||||
* [Modules in Package Sub-directories](#modules-in-package-sub-directories)
|
||||
|
||||
Each of these is described in the following sections. Module source addresses
|
||||
use a _URL-like_ syntax, but with extensions to support unambiguous selection
|
||||
@@ -99,10 +100,10 @@ to get started with Terraform and find modules created by others in the
|
||||
community.
|
||||
|
||||
You can also use a
|
||||
[private registry](/docs/registry/private.html), either
|
||||
[private registry](/registry/private), either
|
||||
via the built-in feature from Terraform Cloud, or by running a custom
|
||||
service that implements
|
||||
[the module registry protocol](/docs/registry/api.html).
|
||||
[the module registry protocol](/registry/api-docs).
|
||||
|
||||
Modules on the public Terraform Registry can be referenced using a registry
|
||||
source address of the form `<NAMESPACE>/<NAME>/<PROVIDER>`, with each
|
||||
@@ -138,13 +139,13 @@ the `remote` backend.
|
||||
|
||||
Registry modules support versioning. You can provide a specific version as shown
|
||||
in the above examples, or use flexible
|
||||
[version constraints](/docs/language/modules/syntax.html#version).
|
||||
[version constraints](/language/modules/syntax#version).
|
||||
|
||||
You can learn more about the registry at the
|
||||
[Terraform Registry documentation](/docs/registry/modules/use.html#using-modules).
|
||||
[Terraform Registry documentation](/registry/modules/use#using-modules).
|
||||
|
||||
To access modules from a private registry, you may need to configure an access
|
||||
token [in the CLI config](/docs/cli/config/config-file.html#credentials). Use the
|
||||
token [in the CLI config](/cli/config/config-file#credentials). Use the
|
||||
same hostname as used in the module source string. For a private registry
|
||||
within Terraform Cloud, use the same authentication token as you would
|
||||
use with the Enterprise API or command-line clients.
|
||||
@@ -231,7 +232,7 @@ to select a suitable source of credentials for your environment.
|
||||
|
||||
If your Terraform configuration will be used within [Terraform Cloud](https://www.hashicorp.com/products/terraform),
|
||||
only SSH key authentication is supported, and
|
||||
[keys can be configured on a per-workspace basis](/docs/cloud/workspaces/ssh-keys.html).
|
||||
[keys can be configured on a per-workspace basis](/cloud-docs/workspaces/settings/ssh-keys).
|
||||
|
||||
### Selecting a Revision
|
||||
|
||||
@@ -266,7 +267,6 @@ module "storage" {
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
If you use the `ssh://` URL scheme then Terraform will assume that the colon
|
||||
marks the beginning of a port number, rather than the beginning of the path.
|
||||
This matches how Git itself interprets these different forms, aside from
|
||||
@@ -297,7 +297,7 @@ repositories without interactive prompts.
|
||||
|
||||
If your Terraform configuration will be used within [Terraform Cloud](https://www.hashicorp.com/products/terraform),
|
||||
only SSH key authentication is supported, and
|
||||
[keys can be configured on a per-workspace basis](/docs/cloud/workspaces/ssh-keys.html).
|
||||
[keys can be configured on a per-workspace basis](/cloud-docs/workspaces/settings/ssh-keys).
|
||||
|
||||
### Selecting a Revision
|
||||
|
||||
@@ -427,7 +427,6 @@ The module installer uses Google Cloud SDK to authenticate with GCS. To set cred
|
||||
* If you're running Terraform from a GCE instance, default credentials are automatically available. See [Creating and Enabling Service Accounts](https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances) for Instances for more details
|
||||
* On your computer, you can make your Google identity available by running `gcloud auth application-default login`.
|
||||
|
||||
|
||||
## Modules in Package Sub-directories
|
||||
|
||||
When the source of a module is a version control repository or archive file
|
||||
@@ -1,8 +1,9 @@
|
||||
---
|
||||
layout: "language"
|
||||
page_title: "Modules - Configuration Language"
|
||||
sidebar_current: "docs-config-modules"
|
||||
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."
|
||||
page_title: Modules - Configuration Language
|
||||
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.
|
||||
---
|
||||
|
||||
# Module Blocks
|
||||
@@ -22,13 +23,13 @@ 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/language/modules/develop/index.html).
|
||||
about creating re-usable child modules, see [Module Development](/language/modules/develop).
|
||||
|
||||
## 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/language/values/variables.html). Modules are called
|
||||
[input variables](/language/values/variables). Modules are called
|
||||
from within other modules using `module` blocks:
|
||||
|
||||
```hcl
|
||||
@@ -52,7 +53,7 @@ Module calls use the following kinds of arguments:
|
||||
|
||||
- The `version` argument is recommended for modules from a registry.
|
||||
|
||||
- Most other arguments correspond to [input variables](/docs/language/values/variables.html)
|
||||
- Most other arguments correspond to [input variables](/language/values/variables)
|
||||
defined by the module. (The `servers` argument in the example above is one of
|
||||
these.)
|
||||
|
||||
@@ -66,7 +67,7 @@ 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/language/modules/sources.html).
|
||||
possible values for this argument, see [Module Sources](/language/modules/sources).
|
||||
|
||||
The same source address can be specified in multiple `module` blocks to create
|
||||
multiple copies of the resources defined within, possibly with different
|
||||
@@ -94,14 +95,14 @@ module "consul" {
|
||||
}
|
||||
```
|
||||
|
||||
The `version` argument accepts a [version constraint string](/docs/language/expressions/version-constraints.html).
|
||||
The `version` argument accepts a [version constraint string](/language/expressions/version-constraints).
|
||||
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).
|
||||
or [Terraform Cloud's private module registry](/cloud-docs/registry).
|
||||
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
|
||||
@@ -115,22 +116,22 @@ 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/language/meta-arguments/count.html)
|
||||
See [the `count` page](/language/meta-arguments/count)
|
||||
for details.
|
||||
|
||||
- `for_each` - Creates multiple instances of a module from a single `module`
|
||||
block. See
|
||||
[the `for_each` page](/docs/language/meta-arguments/for_each.html)
|
||||
[the `for_each` page](/language/meta-arguments/for_each)
|
||||
for details.
|
||||
|
||||
- `providers` - Passes provider configurations to a child module. See
|
||||
[the `providers` page](/docs/language/meta-arguments/module-providers.html)
|
||||
[the `providers` page](/language/meta-arguments/module-providers)
|
||||
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/language/meta-arguments/depends_on.html)
|
||||
[the `depends_on` page](/language/meta-arguments/depends_on)
|
||||
for details.
|
||||
|
||||
In addition to the above, the `lifecycle` argument is not currently used by
|
||||
@@ -140,7 +141,7 @@ Terraform but is reserved for planned future features.
|
||||
|
||||
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/language/values/outputs.html) to selectively
|
||||
declare [output values](/language/values/outputs) to selectively
|
||||
export certain values to be accessed by the calling module.
|
||||
|
||||
For example, if the `./app-cluster` module referenced in the example above
|
||||
@@ -156,7 +157,7 @@ resource "aws_elb" "example" {
|
||||
```
|
||||
|
||||
For more information about referring to named values, see
|
||||
[Expressions](/docs/language/expressions/index.html).
|
||||
[Expressions](/language/expressions).
|
||||
|
||||
## Transferring Resource State Into Modules
|
||||
|
||||
@@ -166,7 +167,7 @@ result, Terraform plans to destroy all resource instances at the old address
|
||||
and create new instances at the new address.
|
||||
|
||||
To preserve existing objects, you can use
|
||||
[refactoring blocks](develop/refactoring.html) to record the old and new
|
||||
[refactoring blocks](/language/modules/develop/refactoring) to record the old and new
|
||||
addresses for each resource instance. This directs Terraform to treat existing
|
||||
objects at the old addresses as if they had originally been created at the
|
||||
corresponding new addresses.
|
||||
@@ -176,7 +177,7 @@ corresponding new addresses.
|
||||
You may have an object that needs to be replaced with a new object for a reason
|
||||
that isn't automatically visible to Terraform, such as if a particular virtual
|
||||
machine is running on degraded underlying hardware. In this case, you can use
|
||||
[the `-replace=...` planning option](/docs/cli/commands/plan.html#replace-address)
|
||||
[the `-replace=...` planning option](/cli/commands/plan#replace-address)
|
||||
to force Terraform to propose replacing that object.
|
||||
|
||||
If the object belongs to a resource within a nested module, specify the full
|
||||
@@ -1,6 +1,5 @@
|
||||
---
|
||||
layout: "language"
|
||||
page_title: "Module Testing Experiment - Configuration Language"
|
||||
page_title: Module Testing Experiment - Configuration Language
|
||||
---
|
||||
|
||||
# Module Testing Experiment
|
||||
Reference in New Issue
Block a user