mirror of
https://github.com/opentofu/opentofu.git
synced 2025-01-27 00:46:25 -06:00
Update website/docs/language/resources (#232)
Signed-off-by: Marcin Białoń <mbialon@spacelift.io>
This commit is contained in:
Marcin Białoń
GitHub
parent
1a3eee582f
commit
f8ee967230
@ -1,7 +1,7 @@
|
||||
---
|
||||
page_title: Resource Behavior - Configuration Language
|
||||
description: >-
|
||||
Learn how Terraform uses resource blocks to create infrastructure objects.
|
||||
Learn how OpenTF uses resource blocks to create infrastructure objects.
|
||||
Also learn about resource dependencies and how to access resource attributes.
|
||||
---
|
||||
|
||||
@ -12,21 +12,21 @@ to exist with the given settings. If you are writing a new configuration for
|
||||
the first time, the resources it defines will exist _only_ in the configuration,
|
||||
and will not yet represent real infrastructure objects in the target platform.
|
||||
|
||||
_Applying_ a Terraform configuration is the process of creating, updating,
|
||||
_Applying_ an OpenTF configuration is the process of creating, updating,
|
||||
and destroying real infrastructure objects in order to make their settings
|
||||
match the configuration.
|
||||
|
||||
## How Terraform Applies a Configuration
|
||||
## How OpenTF Applies a Configuration
|
||||
|
||||
When Terraform creates a new infrastructure object represented by a `resource`
|
||||
block, the identifier for that real object is saved in Terraform's
|
||||
[state](/terraform/language/state), allowing it to be updated and destroyed
|
||||
When OpenTF creates a new infrastructure object represented by a `resource`
|
||||
block, the identifier for that real object is saved in OpenTF's
|
||||
[state](/opentf/language/state), allowing it to be updated and destroyed
|
||||
in response to future changes. For resource blocks that already have an
|
||||
associated infrastructure object in the state, Terraform compares the
|
||||
associated infrastructure object in the state, OpenTF compares the
|
||||
actual configuration of the object with the arguments given in the
|
||||
configuration and, if necessary, updates the object to match the configuration.
|
||||
|
||||
In summary, applying a Terraform configuration will:
|
||||
In summary, applying an OpenTF configuration will:
|
||||
|
||||
- _Create_ resources that exist in the configuration but are not associated with a real infrastructure object in the state.
|
||||
- _Destroy_ resources that exist in the state but no longer exist in the configuration.
|
||||
@ -44,7 +44,7 @@ customized on a per-resource basis.
|
||||
|
||||
## Accessing Resource Attributes
|
||||
|
||||
[Expressions](/terraform/language/expressions) within a Terraform module can access
|
||||
[Expressions](/opentf/language/expressions) within an OpenTF module can access
|
||||
information about resources in the same module, and you can use that information
|
||||
to help configure other resources. Use the `<RESOURCE TYPE>.<NAME>.<ATTRIBUTE>`
|
||||
syntax to reference a resource attribute in an expression.
|
||||
@ -54,7 +54,7 @@ read-only attributes with information obtained from the remote API; this often
|
||||
includes things that can't be known until the resource is created, like the
|
||||
resource's unique random ID.
|
||||
|
||||
Many providers also include [data sources](/terraform/language/data-sources),
|
||||
Many providers also include [data sources](/opentf/language/data-sources),
|
||||
which are a special type of resource used only for looking up information.
|
||||
|
||||
For a list of the attributes a resource or data source type provides, consult
|
||||
@ -62,40 +62,40 @@ its documentation; these are generally included in a second list below its list
|
||||
of configurable arguments.
|
||||
|
||||
For more information about referencing resource attributes in expressions, see
|
||||
[Expressions: References to Resource Attributes](/terraform/language/expressions/references#references-to-resource-attributes).
|
||||
[Expressions: References to Resource Attributes](/opentf/language/expressions/references#references-to-resource-attributes).
|
||||
|
||||
## Resource Dependencies
|
||||
|
||||
Most resources in a configuration don't have any particular relationship, and
|
||||
Terraform can make changes to several unrelated resources in parallel.
|
||||
OpenTF can make changes to several unrelated resources in parallel.
|
||||
|
||||
However, some resources must be processed after other specific resources;
|
||||
sometimes this is because of how the resource works, and sometimes the
|
||||
resource's configuration just requires information generated by another
|
||||
resource.
|
||||
|
||||
Most resource dependencies are handled automatically. Terraform analyses any
|
||||
[expressions](/terraform/language/expressions) within a `resource` block to find references
|
||||
Most resource dependencies are handled automatically. OpenTF analyses any
|
||||
[expressions](/opentf/language/expressions) within a `resource` block to find references
|
||||
to other objects, and treats those references as implicit ordering requirements
|
||||
when creating, updating, or destroying resources. Since most resources with
|
||||
behavioral dependencies on other resources also refer to those resources' data,
|
||||
it's usually not necessary to manually specify dependencies between resources.
|
||||
|
||||
However, some dependencies cannot be recognized implicitly in configuration. For
|
||||
example, if Terraform must manage access control policies _and_ take actions
|
||||
example, if OpenTF must manage access control policies _and_ take actions
|
||||
that require those policies to be present, there is a hidden dependency between
|
||||
the access policy and a resource whose creation depends on it. In these rare
|
||||
cases,
|
||||
[the `depends_on` meta-argument](/terraform/language/meta-arguments/depends_on)
|
||||
[the `depends_on` meta-argument](/opentf/language/meta-arguments/depends_on)
|
||||
can explicitly specify a dependency.
|
||||
|
||||
You can also use the [`replace_triggered_by` meta-argument](/terraform/language/meta-arguments/lifecycle#replace_triggered_by) to add dependencies between otherwise independent resources. It forces Terraform to replace the parent resource when there is a change to a referenced resource or resource attribute.
|
||||
You can also use the [`replace_triggered_by` meta-argument](/opentf/language/meta-arguments/lifecycle#replace_triggered_by) to add dependencies between otherwise independent resources. It forces OpenTF to replace the parent resource when there is a change to a referenced resource or resource attribute.
|
||||
|
||||
## Local-only Resources
|
||||
|
||||
While most resource types correspond to an infrastructure object type that
|
||||
is managed via a remote network API, there are certain specialized resource
|
||||
types that operate only within Terraform itself, calculating some results and
|
||||
types that operate only within OpenTF itself, calculating some results and
|
||||
saving those results in the state for future use.
|
||||
|
||||
For example, local-only resource types exist for
|
||||
@ -107,5 +107,5 @@ managing "real" infrastructure objects, they can be useful as glue to help
|
||||
connect together other resources.
|
||||
|
||||
The behavior of local-only resources is the same as all other resources, but
|
||||
their result data exists only within the Terraform state. "Destroying" such
|
||||
their result data exists only within the OpenTF state. "Destroying" such
|
||||
a resource means only to remove it from the state, discarding its data.
|
||||
|
||||
@ -1,35 +1,33 @@
|
||||
---
|
||||
page_title: Resources Overview - Configuration Language
|
||||
description: >-
|
||||
Resources describe infrastructure objects in Terraform configurations. Find
|
||||
Resources describe infrastructure objects in OpenTF configurations. Find
|
||||
documentation for resource syntax, behavior, and meta-arguments.
|
||||
---
|
||||
|
||||
# Resources
|
||||
|
||||
> **Hands-on:** Try the [Terraform: Get Started](/terraform/tutorials/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorials.
|
||||
|
||||
_Resources_ are the most important element in the Terraform language.
|
||||
_Resources_ are the most important element in the OpenTF language.
|
||||
Each resource block describes one or more infrastructure objects, such
|
||||
as virtual networks, compute instances, or higher-level components such
|
||||
as DNS records.
|
||||
|
||||
- [Resource Blocks](/terraform/language/resources/syntax) documents
|
||||
- [Resource Blocks](/opentf/language/resources/syntax) documents
|
||||
the syntax for declaring resources.
|
||||
|
||||
- [Resource Behavior](/terraform/language/resources/behavior) explains in
|
||||
more detail how Terraform handles resource declarations when applying a
|
||||
- [Resource Behavior](/opentf/language/resources/behavior) explains in
|
||||
more detail how OpenTF handles resource declarations when applying a
|
||||
configuration.
|
||||
|
||||
- The Meta-Arguments section documents special arguments that can be used with
|
||||
every resource type, including
|
||||
[`depends_on`](/terraform/language/meta-arguments/depends_on),
|
||||
[`count`](/terraform/language/meta-arguments/count),
|
||||
[`for_each`](/terraform/language/meta-arguments/for_each),
|
||||
[`provider`](/terraform/language/meta-arguments/resource-provider),
|
||||
and [`lifecycle`](/terraform/language/meta-arguments/lifecycle).
|
||||
[`depends_on`](/opentf/language/meta-arguments/depends_on),
|
||||
[`count`](/opentf/language/meta-arguments/count),
|
||||
[`for_each`](/opentf/language/meta-arguments/for_each),
|
||||
[`provider`](/opentf/language/meta-arguments/resource-provider),
|
||||
and [`lifecycle`](/opentf/language/meta-arguments/lifecycle).
|
||||
|
||||
- [Provisioners](/terraform/language/resources/provisioners/syntax)
|
||||
- [Provisioners](/opentf/language/resources/provisioners/syntax)
|
||||
documents configuring post-creation actions for a resource using the
|
||||
`provisioner` and `connection` blocks. Since provisioners are non-declarative
|
||||
and potentially unpredictable, we strongly recommend that you treat them as a
|
||||
|
||||
@ -11,7 +11,7 @@ Most provisioners require access to the remote resource via SSH or WinRM and
|
||||
expect a nested `connection` block with details about how to connect.
|
||||
|
||||
~> **Important:** Use provisioners as a last resort. There are better alternatives for most situations. Refer to
|
||||
[Declaring Provisioners](/terraform/language/resources/provisioners/syntax) for more details.
|
||||
[Declaring Provisioners](/opentf/language/resources/provisioners/syntax) for more details.
|
||||
|
||||
## Connection Block
|
||||
|
||||
@ -29,12 +29,6 @@ Since the SSH connection type is most often used with
|
||||
newly-created remote resources, validation of SSH host keys is disabled by
|
||||
default. If this is not acceptable, you can establish a separate mechanism for key distribution and explicitly set the `host_key` argument (details below) to verify against a specific key or signing CA.
|
||||
|
||||
-> **Note:** In Terraform 0.11 and earlier, providers could set default values
|
||||
for some connection settings, so that `connection` blocks could sometimes be
|
||||
omitted. This feature was removed in 0.12 in order to make Terraform's behavior
|
||||
more predictable.
|
||||
|
||||
|
||||
### Example usage
|
||||
|
||||
```hcl
|
||||
@ -84,8 +78,8 @@ The `connection` block supports the following arguments. Some arguments are only
|
||||
| `port` | Both| The port to connect to. | `22` for type `"ssh"`<br />`5985` for type `"winrm"` |
|
||||
| `timeout` | Both | The timeout to wait for the connection to become available. Should be provided as a string (e.g., `"30s"` or `"5m"`.) | `"5m"` |
|
||||
| `script_path` | Both | The path used to copy scripts meant for remote execution. Refer to [How Provisioners Execute Remote Scripts](#how-provisioners-execute-remote-scripts) below for more details. | (details below) |
|
||||
| `private_key` | SSH | The contents of an SSH key to use for the connection. These can be loaded from a file on disk using [the `file` function](/terraform/language/functions/file). This takes preference over `password` if provided. | |
|
||||
| `certificate` | SSH | The contents of a signed CA Certificate. The certificate argument must be used in conjunction with a `private_key`. These can be loaded from a file on disk using the [the `file` function](/terraform/language/functions/file). | |
|
||||
| `private_key` | SSH | The contents of an SSH key to use for the connection. These can be loaded from a file on disk using [the `file` function](/opentf/language/functions/file). This takes preference over `password` if provided. | |
|
||||
| `certificate` | SSH | The contents of a signed CA Certificate. The certificate argument must be used in conjunction with a `private_key`. These can be loaded from a file on disk using the [the `file` function](/opentf/language/functions/file). | |
|
||||
| `agent` | SSH | Set to `false` to disable using `ssh-agent` to authenticate. On Windows the only supported SSH authentication agent is [Pageant](http://the.earth.li/\~sgtatham/putty/0.66/htmldoc/Chapter9.html#pageant). | |
|
||||
| `agent_identity` | SSH | The preferred identity from the ssh agent for authentication. | |
|
||||
| `host_key` | SSH | The public key from the remote host or the signing CA, used to verify the connection. | |
|
||||
@ -110,8 +104,8 @@ indirectly with a [bastion host](https://en.wikipedia.org/wiki/Bastion_host).
|
||||
| `bastion_port` | The port to use connect to the bastion host. | The value of the `port` field.|
|
||||
| `bastion_user`| The user for the connection to the bastion host. | The value of the `user` field. |
|
||||
| `bastion_password` | The password to use for the bastion host. | The value of the `password` field. |
|
||||
| `bastion_private_key` | The contents of an SSH key file to use for the bastion host. These can be loaded from a file on disk using [the `file` function](/terraform/language/functions/file). | The value of the `private_key` field. |
|
||||
| `bastion_certificate` | The contents of a signed CA Certificate. The certificate argument must be used in conjunction with a `bastion_private_key`. These can be loaded from a file on disk using the [the `file` function](/terraform/language/functions/file). |
|
||||
| `bastion_private_key` | The contents of an SSH key file to use for the bastion host. These can be loaded from a file on disk using [the `file` function](/opentf/language/functions/file). | The value of the `private_key` field. |
|
||||
| `bastion_certificate` | The contents of a signed CA Certificate. The certificate argument must be used in conjunction with a `bastion_private_key`. These can be loaded from a file on disk using the [the `file` function](/opentf/language/functions/file). |
|
||||
|
||||
## Connection through a HTTP Proxy with SSH
|
||||
|
||||
@ -139,7 +133,7 @@ some unusual situations, even though this is just an implementation detail
|
||||
in typical use.
|
||||
|
||||
Most importantly, there must be a suitable location in the remote filesystem
|
||||
where the provisioner can create the script file. By default, Terraform
|
||||
where the provisioner can create the script file. By default, OpenTF
|
||||
chooses a path containing a random number using the following patterns
|
||||
depending on how `target_platform` is set:
|
||||
|
||||
@ -151,7 +145,7 @@ some randomly-chosen decimal digits.
|
||||
|
||||
Provisioners cannot react directly to remote environment variables such as
|
||||
`TMPDIR` or use functions like `mktemp` because they run on the system where
|
||||
Terraform is running, not on the remote system. Therefore if your remote
|
||||
OpenTF is running, not on the remote system. Therefore if your remote
|
||||
system doesn't use the filesystem layout expected by these default paths
|
||||
then you can override it using the `script_path` option in your `connection`
|
||||
block:
|
||||
@ -159,7 +153,7 @@ block:
|
||||
```hcl
|
||||
connection {
|
||||
# ...
|
||||
script_path = "H:/terraform-temp/script_%RAND%.sh"
|
||||
script_path = "H:/opentf-temp/script_%RAND%.sh"
|
||||
}
|
||||
```
|
||||
|
||||
@ -169,7 +163,7 @@ between multiple provisioners running concurrently.
|
||||
|
||||
If your target system is running Windows, we recommend using forward slashes
|
||||
instead of backslashes, despite the typical convention on Windows, because
|
||||
the Terraform language uses backslash as the quoted string escape character.
|
||||
the OpenTF language uses backslash as the quoted string escape character.
|
||||
|
||||
### Executing Scripts using SSH/SCP
|
||||
|
||||
@ -187,15 +181,6 @@ user by specifying a relative path:
|
||||
connection {
|
||||
type = "ssh"
|
||||
# ...
|
||||
script_path = "terraform_provisioner_%RAND%.sh"
|
||||
script_path = "opentf_provisioner_%RAND%.sh"
|
||||
}
|
||||
```
|
||||
|
||||
!> **Warning:** In Terraform v1.0 and earlier, the built-in provisioners
|
||||
incorrectly passed the `script_path` value to `scp` through a remote shell and
|
||||
thus allowed it to be subject to arbitrary shell expansion, and thus created an
|
||||
unintended opportunity for remote code execution. Terraform v1.1 and later
|
||||
will now correctly quote and escape the script path to ensure that the
|
||||
remote `scp` process can always interpret it literally. For modules that will
|
||||
be used with Terraform v1.0 and earlier, avoid using untrusted external
|
||||
values as part of the `script_path` argument.
|
||||
|
||||
@ -2,18 +2,18 @@
|
||||
page_title: 'Provisioner: file'
|
||||
description: >-
|
||||
The `file` provisioner is used to copy files or directories from the machine
|
||||
executing Terraform to the newly created resource. The `file` provisioner
|
||||
executing OpenTF to the newly created resource. The `file` provisioner
|
||||
supports both `ssh` and `winrm` type connections.
|
||||
---
|
||||
|
||||
# File Provisioner
|
||||
|
||||
The `file` provisioner copies files or directories from the machine
|
||||
running Terraform to the newly created resource. The `file` provisioner
|
||||
supports both `ssh` and `winrm` type [connections](/terraform/language/resources/provisioners/connection).
|
||||
running OpenTF to the newly created resource. The `file` provisioner
|
||||
supports both `ssh` and `winrm` type [connections](/opentf/language/resources/provisioners/connection).
|
||||
|
||||
~> **Important:** Use provisioners as a last resort. There are better alternatives for most situations. Refer to
|
||||
[Declaring Provisioners](/terraform/language/resources/provisioners/syntax) for more details.
|
||||
[Declaring Provisioners](/opentf/language/resources/provisioners/syntax) for more details.
|
||||
|
||||
## Example usage
|
||||
|
||||
@ -70,7 +70,7 @@ The following arguments are supported:
|
||||
## Destination Paths
|
||||
|
||||
The path you provide in the `destination` argument will be evaluated by the
|
||||
remote system, rather than by Terraform itself. Therefore the valid values
|
||||
remote system, rather than by OpenTF itself. Therefore the valid values
|
||||
for that argument can vary depending on the operating system and remote access
|
||||
software running on the target.
|
||||
|
||||
@ -122,7 +122,7 @@ destination will be created. For example:
|
||||
* If the source is `/foo` (no trailing slash), and the destination is `/tmp`,
|
||||
then the contents of `/foo` on the local machine will be uploaded to
|
||||
`/tmp/foo` on the remote machine. The `foo` directory on the remote machine
|
||||
will be created by Terraform.
|
||||
will be created by OpenTF.
|
||||
|
||||
* If the source, however, is `/foo/` (a trailing slash is present), and the
|
||||
destination is `/tmp`, then the contents of `/foo` will be uploaded directly
|
||||
|
||||
@ -2,16 +2,16 @@
|
||||
page_title: 'Provisioner: local-exec'
|
||||
description: >-
|
||||
The `local-exec` provisioner invokes a local executable after a resource is
|
||||
created. This invokes a process on the machine running Terraform, not on the
|
||||
created. This invokes a process on the machine running OpenTF, not on the
|
||||
resource. See the `remote-exec` provisioner to run commands on the resource.
|
||||
---
|
||||
|
||||
# local-exec Provisioner
|
||||
|
||||
The `local-exec` provisioner invokes a local executable after a resource is
|
||||
created. This invokes a process on the machine running Terraform, not on the
|
||||
created. This invokes a process on the machine running OpenTF, not on the
|
||||
resource. See the `remote-exec`
|
||||
[provisioner](/terraform/language/resources/provisioners/remote-exec) to run commands on the
|
||||
[provisioner](/opentf/language/resources/provisioners/remote-exec) to run commands on the
|
||||
resource.
|
||||
|
||||
Note that even though the resource will be fully created when the provisioner is
|
||||
@ -19,7 +19,7 @@ run, there is no guarantee that it will be in an operable state - for example
|
||||
system services such as `sshd` may not be started yet on compute resources.
|
||||
|
||||
~> **Important:** Use provisioners as a last resort. There are better alternatives for most situations. Refer to
|
||||
[Declaring Provisioners](/terraform/language/resources/provisioners/syntax) for more details.
|
||||
[Declaring Provisioners](/opentf/language/resources/provisioners/syntax) for more details.
|
||||
|
||||
## Example usage
|
||||
|
||||
@ -39,7 +39,7 @@ The following arguments are supported:
|
||||
|
||||
* `command` - (Required) This is the command to execute. It can be provided
|
||||
as a relative path to the current working directory or as an absolute path.
|
||||
It is evaluated in a shell, and can use environment variables or Terraform
|
||||
It is evaluated in a shell, and can use environment variables or OpenTF
|
||||
variables.
|
||||
|
||||
* `working_dir` - (Optional) If provided, specifies the working directory where
|
||||
@ -57,12 +57,12 @@ The following arguments are supported:
|
||||
* `environment` - (Optional) block of key value pairs representing the
|
||||
environment of the executed command. inherits the current process environment.
|
||||
|
||||
* `when` - (Optional) If provided, specifies when Terraform will execute the command.
|
||||
* `when` - (Optional) If provided, specifies when OpenTF will execute the command.
|
||||
For example, `when = destroy` specifies that the provisioner will run when the associated resource
|
||||
is destroyed. Refer to [Destroy-Time Provisioners](/terraform/language/resources/provisioners/syntax#destroy-time-provisioners)
|
||||
is destroyed. Refer to [Destroy-Time Provisioners](/opentf/language/resources/provisioners/syntax#destroy-time-provisioners)
|
||||
for details.
|
||||
|
||||
* `quiet` - (Optional) If set to `true`, Terraform will not print the command to be executed to stdout, and will instead print "Suppressed by quiet=true". Note that the output of the command will still be printed in any case.
|
||||
* `quiet` - (Optional) If set to `true`, OpenTF will not print the command to be executed to stdout, and will instead print "Suppressed by quiet=true". Note that the output of the command will still be printed in any case.
|
||||
|
||||
### Interpreter Examples
|
||||
|
||||
|
||||
@ -10,16 +10,16 @@ description: >-
|
||||
If you need to run provisioners that aren't directly associated with a specific
|
||||
resource, you can associate them with a `terraform_data`.
|
||||
|
||||
Instances of [`terraform_data`](/terraform/language/resources/tf-data) are treated
|
||||
Instances of [`terraform_data`](/opentf/language/resources/tf-data) are treated
|
||||
like normal resources, but they don't do anything. Like with any other resource
|
||||
type, you can configure [provisioners](/terraform/language/resources/provisioners/syntax)
|
||||
and [connection details](/terraform/language/resources/provisioners/connection) on a
|
||||
type, you can configure [provisioners](/opentf/language/resources/provisioners/syntax)
|
||||
and [connection details](/opentf/language/resources/provisioners/connection) on a
|
||||
`terraform_data` resource. You can also use its `input` argument, `triggers_replace` argument, and any
|
||||
meta-arguments to control exactly where in the dependency graph its
|
||||
provisioners will run.
|
||||
|
||||
~> **Important:** Use provisioners as a last resort. There are better alternatives for most situations. Refer to
|
||||
[Declaring Provisioners](/terraform/language/resources/provisioners/syntax) for more details.
|
||||
[Declaring Provisioners](/opentf/language/resources/provisioners/syntax) for more details.
|
||||
|
||||
## Example usage
|
||||
|
||||
|
||||
@ -13,12 +13,12 @@ description: >-
|
||||
The `remote-exec` provisioner invokes a script on a remote resource after it
|
||||
is created. This can be used to run a configuration management tool, bootstrap
|
||||
into a cluster, etc. To invoke a local process, see the `local-exec`
|
||||
[provisioner](/terraform/language/resources/provisioners/local-exec) instead. The `remote-exec`
|
||||
provisioner requires a [connection](/terraform/language/resources/provisioners/connection)
|
||||
[provisioner](/opentf/language/resources/provisioners/local-exec) instead. The `remote-exec`
|
||||
provisioner requires a [connection](/opentf/language/resources/provisioners/connection)
|
||||
and supports both `ssh` and `winrm`.
|
||||
|
||||
~> **Important:** Use provisioners as a last resort. There are better alternatives for most situations. Refer to
|
||||
[Declaring Provisioners](/terraform/language/resources/provisioners/syntax) for more details.
|
||||
[Declaring Provisioners](/opentf/language/resources/provisioners/syntax) for more details.
|
||||
|
||||
## Example usage
|
||||
|
||||
@ -60,14 +60,14 @@ The following arguments are supported:
|
||||
that will be copied to the remote resource and then executed. They are executed
|
||||
in the order they are provided. This cannot be provided with `inline` or `script`.
|
||||
|
||||
-> **Note:** Since `inline` is implemented by concatenating commands into a script, [`on_failure`](/terraform/language/resources/provisioners/syntax#failure-behavior) applies only to the final command in the list. In particular, with `on_failure = fail` (the default behaviour) earlier commands will be allowed to fail, and later commands will also execute. If this behaviour is not desired, consider using `"set -o errexit"` as the first command.
|
||||
-> **Note:** Since `inline` is implemented by concatenating commands into a script, [`on_failure`](/opentf/language/resources/provisioners/syntax#failure-behavior) applies only to the final command in the list. In particular, with `on_failure = fail` (the default behaviour) earlier commands will be allowed to fail, and later commands will also execute. If this behaviour is not desired, consider using `"set -o errexit"` as the first command.
|
||||
|
||||
## Script Arguments
|
||||
|
||||
You cannot pass any arguments to scripts using the `script` or
|
||||
`scripts` arguments to this provisioner. If you want to specify arguments,
|
||||
upload the script with the
|
||||
[file provisioner](/terraform/language/resources/provisioners/file)
|
||||
[file provisioner](/opentf/language/resources/provisioners/file)
|
||||
and then use `inline` to call it. Example:
|
||||
|
||||
```hcl
|
||||
|
||||
@ -11,22 +11,18 @@ You can use provisioners to model specific actions on the local machine or on
|
||||
a remote machine in order to prepare servers or other infrastructure objects
|
||||
for service.
|
||||
|
||||
-> **Note:** We removed the Chef, Habitat, Puppet, and Salt Masterless provisioners in Terraform v0.15.0. Information about these legacy provisioners is still available in the documentation for [Terraform v1.1 (and earlier)](/terraform/language/v1.1.x/resources/provisioners/syntax).
|
||||
|
||||
## Provisioners are a Last Resort
|
||||
|
||||
> **Hands-on:** Try the [Provision Infrastructure Deployed with Terraform](/terraform/tutorials/provision?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorials to learn about more declarative ways to handle provisioning actions.
|
||||
|
||||
Terraform includes the concept of provisioners as a measure of pragmatism,
|
||||
OpenTF includes the concept of provisioners as a measure of pragmatism,
|
||||
knowing that there are always certain behaviors that cannot be directly
|
||||
represented in Terraform's declarative model.
|
||||
represented in OpenTF's declarative model.
|
||||
|
||||
However, they also add a considerable amount of complexity and uncertainty to
|
||||
Terraform usage. Firstly, Terraform cannot model the actions of provisioners
|
||||
OpenTF usage. Firstly, OpenTF cannot model the actions of provisioners
|
||||
as part of a plan because they can in principle take any action. Secondly,
|
||||
successful use of provisioners requires coordinating many more details than
|
||||
Terraform usage usually requires: direct network access to your servers,
|
||||
issuing Terraform credentials to log in, making sure that all of the necessary
|
||||
OpenTF usage usually requires: direct network access to your servers,
|
||||
issuing OpenTF credentials to log in, making sure that all of the necessary
|
||||
external software is installed, etc.
|
||||
|
||||
The following sections describe some situations which can be solved with
|
||||
@ -78,8 +74,6 @@ process in various ways data passed via the means described above, allowing
|
||||
you to run arbitrary scripts and do basic system configuration immediately
|
||||
during the boot process and without the need to access the machine over SSH.
|
||||
|
||||
> **Hands-on:** Try the [Provision Infrastructure with Cloud-Init](/terraform/tutorials/provision/cloud-init?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial.
|
||||
|
||||
If you are building custom machine images, you can make use of the "user data"
|
||||
or "metadata" passed by the above means in whatever way makes sense to your
|
||||
application, by referring to your vendor's documentation on how to access the
|
||||
@ -87,19 +81,19 @@ data at runtime.
|
||||
|
||||
This approach is _required_ if you intend to use any mechanism in your cloud
|
||||
provider for automatically launching and destroying servers in a group,
|
||||
because in that case individual servers will launch unattended while Terraform
|
||||
because in that case individual servers will launch unattended while OpenTF
|
||||
is not around to provision them.
|
||||
|
||||
Even if you're deploying individual servers directly with Terraform, passing
|
||||
Even if you're deploying individual servers directly with OpenTF, passing
|
||||
data this way will allow faster boot times and simplify deployment by avoiding
|
||||
the need for direct network access from Terraform to the new server and for
|
||||
the need for direct network access from OpenTF to the new server and for
|
||||
remote access credentials to be provided.
|
||||
|
||||
### Provisioning files using cloud-config
|
||||
|
||||
You can add the [`cloudinit_config`](https://registry.terraform.io/providers/hashicorp/cloudinit/latest/docs) data source to your Terraform configuration and specify the files you want to provision as `text/cloud-config` content. The `cloudinit_config` data source renders multi-part MIME configurations for use with [cloud-init](https://cloudinit.readthedocs.io/en/latest/). Pass the files in the `content` field as YAML-encoded configurations using the `write_files` block.
|
||||
You can add the [`cloudinit_config`](https://registry.terraform.io/providers/hashicorp/cloudinit/latest/docs) data source to your OpenTF configuration and specify the files you want to provision as `text/cloud-config` content. The `cloudinit_config` data source renders multi-part MIME configurations for use with [cloud-init](https://cloudinit.readthedocs.io/en/latest/). Pass the files in the `content` field as YAML-encoded configurations using the `write_files` block.
|
||||
|
||||
In the following example, the `my_cloud_config` data source specifies a `text/cloud-config` MIME part named `cloud.conf`. The `part.content` field is set to [`yamlencode`](/terraform/language/functions/yamlencode), which encodes the `write_files` JSON object as YAML so that the system can provision the referenced files.
|
||||
In the following example, the `my_cloud_config` data source specifies a `text/cloud-config` MIME part named `cloud.conf`. The `part.content` field is set to [`yamlencode`](/opentf/language/functions/yamlencode), which encodes the `write_files` JSON object as YAML so that the system can provision the referenced files.
|
||||
|
||||
```hcl
|
||||
data "cloudinit_config" "my_cloud_config" {
|
||||
@ -134,7 +128,7 @@ data "cloudinit_config" "my_cloud_config" {
|
||||
### Running configuration management software
|
||||
|
||||
As a convenience to users who are forced to use generic operating system
|
||||
distribution images, Terraform includes a number of specialized provisioners
|
||||
distribution images, OpenTF includes a number of specialized provisioners
|
||||
for launching specific configuration management products.
|
||||
|
||||
We strongly recommend not using these, and instead running system configuration
|
||||
@ -144,26 +138,24 @@ configuration management provisioners and can run their installation steps
|
||||
during a separate build process, before creating a system disk image that you
|
||||
can deploy many times.
|
||||
|
||||
> **Hands-on:** Try the [Provision Infrastructure with Packer](/terraform/tutorials/provision/packer?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial.
|
||||
|
||||
If you are using configuration management software that has a centralized server
|
||||
component, you will need to delay the _registration_ step until the final
|
||||
system is booted from your custom image. To achieve that, use one of the
|
||||
mechanisms described above to pass the necessary information into each instance
|
||||
so that it can register itself with the configuration management server
|
||||
immediately on boot, without the need to accept commands from Terraform over
|
||||
immediately on boot, without the need to accept commands from OpenTF over
|
||||
SSH or WinRM.
|
||||
|
||||
### First-class Terraform provider functionality may be available
|
||||
### First-class provider functionality may be available
|
||||
|
||||
It is technically possible to use the `local-exec` provisioner to run the CLI
|
||||
for your target system in order to create, update, or otherwise interact with
|
||||
remote objects in that system.
|
||||
|
||||
If you are trying to use a new feature of the remote system that isn't yet
|
||||
supported in its Terraform provider, that might be the only option. However,
|
||||
supported in its provider, that might be the only option. However,
|
||||
if there _is_ provider support for the feature you intend to use, prefer to
|
||||
use that provider functionality rather than a provisioner so that Terraform
|
||||
use that provider functionality rather than a provisioner so that OpenTF
|
||||
can be fully aware of the object and properly manage ongoing changes to it.
|
||||
|
||||
Even if the functionality you need is not available in a provider today, we
|
||||
@ -199,11 +191,11 @@ resource "aws_instance" "web" {
|
||||
|
||||
The `local-exec` provisioner requires no other configuration, but most other
|
||||
provisioners must connect to the remote system using SSH or WinRM.
|
||||
You must include [a `connection` block](/terraform/language/resources/provisioners/connection) so that Terraform knows how to communicate with the server.
|
||||
You must include [a `connection` block](/opentf/language/resources/provisioners/connection) so that OpenTF knows how to communicate with the server.
|
||||
|
||||
Terraform includes several built-in provisioners. You can also use third-party provisioners as plugins, by placing them
|
||||
OpenTF includes several built-in provisioners. You can also use third-party provisioners as plugins, by placing them
|
||||
in `%APPDATA%\terraform.d\plugins`, `~/.terraform.d/plugins`, or the same
|
||||
directory where the Terraform binary is installed. However, we do not recommend
|
||||
directory where the OpenTF binary is installed. However, we do not recommend
|
||||
using any provisioners except the built-in `file`, `local-exec`, and
|
||||
`remote-exec` provisioners.
|
||||
|
||||
@ -227,8 +219,8 @@ block would create a dependency cycle.
|
||||
## Suppressing Provisioner Logs in CLI Output
|
||||
|
||||
The configuration for a `provisioner` block may use sensitive values, such as
|
||||
[`sensitive` variables](/terraform/language/values/variables#suppressing-values-in-cli-output) or
|
||||
[`sensitive` output values](/terraform/language/values/outputs#sensitive-suppressing-values-in-cli-output).
|
||||
[`sensitive` variables](/opentf/language/values/variables#suppressing-values-in-cli-output) or
|
||||
[`sensitive` output values](/opentf/language/values/outputs#sensitive-suppressing-values-in-cli-output).
|
||||
In this case, all log output from the provisioner is automatically suppressed to
|
||||
prevent the sensitive values from being displayed.
|
||||
|
||||
@ -241,8 +233,8 @@ bootstrapping of a system.
|
||||
|
||||
If a creation-time provisioner fails, the resource is marked as **tainted**.
|
||||
A tainted resource will be planned for destruction and recreation upon the
|
||||
next `terraform apply`. Terraform does this because a failed provisioner
|
||||
can leave a resource in a semi-configured state. Because Terraform cannot
|
||||
next `opentf apply`. OpenTF does this because a failed provisioner
|
||||
can leave a resource in a semi-configured state. Because OpenTF cannot
|
||||
reason about what the provisioner does, the only way to ensure proper creation
|
||||
of a resource is to recreate it. This is tainting.
|
||||
|
||||
@ -266,11 +258,11 @@ resource "aws_instance" "web" {
|
||||
```
|
||||
|
||||
Destroy provisioners are run before the resource is destroyed. If they
|
||||
fail, Terraform will error and rerun the provisioners again on the next
|
||||
`terraform apply`. Due to this behavior, care should be taken for destroy
|
||||
fail, OpenTF will error and rerun the provisioners again on the next
|
||||
`opentf apply`. Due to this behavior, care should be taken for destroy
|
||||
provisioners to be safe to run multiple times.
|
||||
|
||||
~> **Note**: Destroy provisioners of this resource do not run if `create_before_destroy` is set to `true`. This [GitHub issue](https://github.com/hashicorp/terraform/issues/13549) contains more details.
|
||||
~> **Note**: Destroy provisioners of this resource do not run if `create_before_destroy` is set to `true`.
|
||||
|
||||
Destroy-time provisioners can only run if they remain in the configuration
|
||||
at the time a resource is destroyed. If a resource block with a destroy-time
|
||||
@ -286,7 +278,7 @@ remove a resource with a destroy-time provisioner:
|
||||
|
||||
Because of this limitation, you should use destroy-time provisioners sparingly and with care.
|
||||
|
||||
~> **NOTE:** A destroy-time provisioner within a resource that is tainted _will not_ run. This includes resources that are marked tainted from a failed creation-time provisioner or tainted manually using `terraform taint`.
|
||||
~> **NOTE:** A destroy-time provisioner within a resource that is tainted _will not_ run. This includes resources that are marked tainted from a failed creation-time provisioner or tainted manually using `opentf taint`.
|
||||
|
||||
## Multiple Provisioners
|
||||
|
||||
@ -316,7 +308,7 @@ resource "aws_instance" "web" {
|
||||
|
||||
## Failure Behavior
|
||||
|
||||
By default, provisioners that fail will also cause the Terraform apply
|
||||
By default, provisioners that fail will also cause the OpenTF apply
|
||||
itself to fail. The `on_failure` setting can be used to change this. The
|
||||
allowed values are:
|
||||
|
||||
|
||||
@ -8,9 +8,7 @@ description: >-
|
||||
|
||||
# Resource Blocks
|
||||
|
||||
> **Hands-on:** Try the [Terraform: Get Started](/terraform/tutorials/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorials.
|
||||
|
||||
_Resources_ are the most important element in the Terraform language.
|
||||
_Resources_ are the most important element in the OpenTF language.
|
||||
Each resource block describes one or more infrastructure objects, such
|
||||
as virtual networks, compute instances, or higher-level components such
|
||||
as DNS records.
|
||||
@ -31,7 +29,7 @@ resource "aws_instance" "web" {
|
||||
|
||||
A `resource` block declares a resource of a given type ("aws_instance")
|
||||
with a given local name ("web"). The name is used to refer to this resource
|
||||
from elsewhere in the same Terraform module, but has no significance outside
|
||||
from elsewhere in the same module, but has no significance outside
|
||||
that module's scope.
|
||||
|
||||
The resource type and name together serve as an identifier for a given
|
||||
@ -53,29 +51,29 @@ attributes the resource supports.
|
||||
|
||||
### Providers
|
||||
|
||||
Each resource type is implemented by a [provider](/terraform/language/providers/requirements),
|
||||
which is a plugin for Terraform that offers a collection of resource types. A
|
||||
Each resource type is implemented by a [provider](/opentf/language/providers/requirements),
|
||||
which is a plugin for OpenTF that offers a collection of resource types. A
|
||||
provider usually provides resources to manage a single cloud or on-premises
|
||||
infrastructure platform. Providers are distributed separately from Terraform
|
||||
itself, but Terraform can automatically install most providers when initializing
|
||||
infrastructure platform. Providers are distributed separately from OpenTF
|
||||
itself, but OpenTF can automatically install most providers when initializing
|
||||
a working directory.
|
||||
|
||||
In order to manage resources, a Terraform module must specify which providers it
|
||||
In order to manage resources, a module must specify which providers it
|
||||
requires. Additionally, most providers need some configuration in order to
|
||||
access their remote APIs, and the root module must provide that configuration.
|
||||
|
||||
For more information, see:
|
||||
|
||||
- [Provider Requirements](/terraform/language/providers/requirements), for declaring which
|
||||
- [Provider Requirements](/opentf/language/providers/requirements), for declaring which
|
||||
providers a module uses.
|
||||
- [Provider Configuration](/terraform/language/providers/configuration), for configuring provider settings.
|
||||
- [Provider Configuration](/opentf/language/providers/configuration), for configuring provider settings.
|
||||
|
||||
Terraform usually automatically determines which provider to use based on a
|
||||
OpenTF usually automatically determines which provider to use based on a
|
||||
resource type's name. (By convention, resource type names start with their
|
||||
provider's preferred local name.) When using multiple configurations of a
|
||||
provider (or non-preferred local provider names), you must use the `provider`
|
||||
meta-argument to manually choose an alternate provider configuration. See
|
||||
[the `provider` meta-argument](/terraform/language/meta-arguments/resource-provider) for more details.
|
||||
[the `provider` meta-argument](/opentf/language/meta-arguments/resource-provider) for more details.
|
||||
|
||||
### Resource Arguments
|
||||
|
||||
@ -84,51 +82,51 @@ selected resource type. The resource type's documentation lists which arguments
|
||||
are available and how their values should be formatted.
|
||||
|
||||
The values for resource arguments can make full use of
|
||||
[expressions](/terraform/language/expressions) and other dynamic Terraform
|
||||
[expressions](/opentf/language/expressions) and other dynamic OpenTF
|
||||
language features.
|
||||
|
||||
There are also some _meta-arguments_ that are defined by Terraform itself
|
||||
There are also some _meta-arguments_ that are defined by OpenTF itself
|
||||
and apply across all resource types. (See [Meta-Arguments](#meta-arguments) below.)
|
||||
|
||||
### Documentation for Resource Types
|
||||
|
||||
Every Terraform provider has its own documentation, describing its resource
|
||||
Every provider has its own documentation, describing its resource
|
||||
types and their arguments.
|
||||
|
||||
Most publicly available providers are distributed on the
|
||||
[Terraform Registry](https://registry.terraform.io/browse/providers), which also
|
||||
hosts their documentation. When viewing a provider's page on the Terraform
|
||||
[Public Terraform Registry](https://registry.terraform.io/browse/providers), which also
|
||||
hosts their documentation. When viewing a provider's page on the OpenTF
|
||||
Registry, you can click the "Documentation" link in the header to browse its
|
||||
documentation. Provider documentation on the registry is versioned, and you can
|
||||
use the dropdown version menu in the header to switch which version's
|
||||
documentation you are viewing.
|
||||
|
||||
To browse the publicly available providers and their documentation, see
|
||||
[the providers section of the Terraform Registry](https://registry.terraform.io/browse/providers).
|
||||
To browse the publicly available providers and their documentation, see the
|
||||
[Public Terraform Registry](https://registry.terraform.io/browse/providers).
|
||||
|
||||
-> **Note:** Provider documentation previously existed as part of Terraform's core documentation. Although some provider documentation
|
||||
might still be hosted here, the Terraform Registry is now the main home for all
|
||||
-> **Note:** Provider documentation previously existed as part of OpenTF's core documentation. Although some provider documentation
|
||||
might still be hosted here, the Public Terraform Registry is now the main home for all
|
||||
public provider docs.
|
||||
|
||||
## Resource Behavior
|
||||
|
||||
For more information about how Terraform manages resources when applying a
|
||||
For more information about how OpenTF manages resources when applying a
|
||||
configuration, see
|
||||
[Resource Behavior](/terraform/language/resources/behavior).
|
||||
[Resource Behavior](/opentf/language/resources/behavior).
|
||||
|
||||
## Meta-Arguments
|
||||
|
||||
The Terraform language defines several meta-arguments, which can be used with
|
||||
The OpenTF language defines several meta-arguments, which can be used with
|
||||
any resource type to change the behavior of resources.
|
||||
|
||||
The following meta-arguments are documented on separate pages:
|
||||
|
||||
- [`depends_on`, for specifying hidden dependencies](/terraform/language/meta-arguments/depends_on)
|
||||
- [`count`, for creating multiple resource instances according to a count](/terraform/language/meta-arguments/count)
|
||||
- [`for_each`, to create multiple instances according to a map, or set of strings](/terraform/language/meta-arguments/for_each)
|
||||
- [`provider`, for selecting a non-default provider configuration](/terraform/language/meta-arguments/resource-provider)
|
||||
- [`lifecycle`, for lifecycle customizations](/terraform/language/meta-arguments/lifecycle)
|
||||
- [`provisioner`, for taking extra actions after resource creation](/terraform/language/resources/provisioners/syntax)
|
||||
- [`depends_on`, for specifying hidden dependencies](/opentf/language/meta-arguments/depends_on)
|
||||
- [`count`, for creating multiple resource instances according to a count](/opentf/language/meta-arguments/count)
|
||||
- [`for_each`, to create multiple instances according to a map, or set of strings](/opentf/language/meta-arguments/for_each)
|
||||
- [`provider`, for selecting a non-default provider configuration](/opentf/language/meta-arguments/resource-provider)
|
||||
- [`lifecycle`, for lifecycle customizations](/opentf/language/meta-arguments/lifecycle)
|
||||
- [`provisioner`, for taking extra actions after resource creation](/opentf/language/resources/provisioners/syntax)
|
||||
|
||||
## Custom Condition Checks
|
||||
|
||||
@ -152,7 +150,7 @@ resource "aws_instance" "example" {
|
||||
|
||||
Custom conditions can help capture assumptions, helping future maintainers understand the configuration design and intent. They also return useful information about errors earlier and in context, helping consumers more easily diagnose issues in their configurations.
|
||||
|
||||
Refer to [Custom Condition Checks](/terraform/language/expressions/custom-conditions#preconditions-and-postconditions) for more details.
|
||||
Refer to [Custom Condition Checks](/opentf/language/expressions/custom-conditions#preconditions-and-postconditions) for more details.
|
||||
|
||||
## Operation Timeouts
|
||||
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
page_title: The terraform_data Managed Resource Type
|
||||
description: >-
|
||||
Retrieves the root module output values from a Terraform state snapshot stored
|
||||
Retrieves the root module output values from an OpenTF state snapshot stored
|
||||
in a remote backend.
|
||||
---
|
||||
|
||||
# The `terraform_data` Managed Resource Type
|
||||
|
||||
The `terraform_data` implements the standard resource lifecycle, but does not directly take any other actions.
|
||||
You can use the `terraform_data` resource without requiring or configuring a provider. It is always available through a built-in provider with the [source address](/terraform/language/providers/requirements#source-addresses) `terraform.io/builtin/terraform`.
|
||||
The `terraform_data` implements the standard resource lifecycle, but does not directly take any other actions.
|
||||
You can use the `terraform_data` resource without requiring or configuring a provider. It is always available through a built-in provider with the [source address](/opentf/language/providers/requirements#source-addresses) `terraform.io/builtin/terraform`.
|
||||
|
||||
The `terraform_data` resource is useful for storing values which need to follow a manage resource lifecycle, and for triggering provisioners when there is no other logical managed resource in which to place them.
|
||||
|
||||
@ -16,9 +16,9 @@ The `terraform_data` resource is useful for storing values which need to follow
|
||||
## Example Usage (data for `replace_triggered_by`)
|
||||
|
||||
|
||||
[The `replace_triggered_by` lifecycle argument](/terraform/language/meta-arguments/lifecycle#replace_triggered_by) requires all of the given addresses to be for resources, because the decision to force replacement is based on the planned actions for all of the mentioned resources.
|
||||
[The `replace_triggered_by` lifecycle argument](/opentf/language/meta-arguments/lifecycle#replace_triggered_by) requires all of the given addresses to be for resources, because the decision to force replacement is based on the planned actions for all of the mentioned resources.
|
||||
|
||||
Plain data values such as [Local Values](/terraform/language/values/locals) and [Input Variables](/terraform/language/values/variables) don't have any side-effects to plan against and so they aren't valid in `replace_triggered_by`. You can use `terraform_data`'s behavior of planning an action each time `input` changes to _indirectly_ use a plain value to trigger replacement.
|
||||
Plain data values such as [Local Values](/opentf/language/values/locals) and [Input Variables](/opentf/language/values/variables) don't have any side-effects to plan against and so they aren't valid in `replace_triggered_by`. You can use `terraform_data`'s behavior of planning an action each time `input` changes to _indirectly_ use a plain value to trigger replacement.
|
||||
|
||||
|
||||
```hcl
|
||||
|
||||
Loading…
Reference in New Issue
Block a user