diff --git a/website/data/language-nav-data.json b/website/data/language-nav-data.json index 35f869ea92..e82b199ff1 100644 --- a/website/data/language-nav-data.json +++ b/website/data/language-nav-data.json @@ -94,6 +94,10 @@ "path": "resources/provisioners/remote-exec" } ] + }, + { + "title": "The terraform_data Resource", + "path": "resources/terraform-data" } ] }, diff --git a/website/docs/language/resources/terraform-data.mdx b/website/docs/language/resources/terraform-data.mdx new file mode 100644 index 0000000000..c573c0feee --- /dev/null +++ b/website/docs/language/resources/terraform-data.mdx @@ -0,0 +1,95 @@ +--- +page_title: The terraform_data Managed Resource +description: >- + Retrieves the root module output values from a Terraform state snapshot stored + in a remote backend. +--- + +# The `terraform_data` Resource + +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](/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. + + +## Example Usage (data for `replace_triggered_by`) + +```hcl +variable "revision" { + default = 1 +} + +resource "terraform_data" "replacement" { + input = var.revision +} + +# This resource has no convenient attribute which forces replacement, +# but can now be replaced by any change to the revision variable value. +resource "example_database" "test" { + lifecycle { + replace_triggered_by = [terraform_data.replacement] + } +} +``` + +## Example Usage (`null_resource` replacement) + +```hcl +resource "aws_instance" "web" { + # ... +} + +# A use-case for terraform_data is as a do-nothing container +# for arbitrary actions taken by a provisioner. +resource "terraform_data" "bootstrap" { + triggers_replace = aws_instance.web.id + + connection { + host = aws_instance.web.public_ip + } + + provisioner "remote-exec" { + inline = [ + "bootstrap-host.sh, + ] + } +} +``` + +## Example Usage (force computed value) + +```hcl +resource "example_resource" "test" { + name = "foo" +} + +resource "terraform_data" "example" { + input = example_resource.test.name +} + +# This resource has a problem where it will fail during plan if the +# contains list of resources has not yet been created. +resource "example_broken_collection" "test" { + # terraform_data.example.output will stand in as a computed attribute + # for example_resource.test, which will be unknown until after apply. + contains = [terraform_data.example.output] +} +``` + + +## Argument Reference + +The following arguments are supported: + +* `input` - (Optional) A value which will be stored in the instance state, and reflected in the `output` attribute after apply. + +* `triggers_replace` - (Optional) A value which is stored in the instance state, and will force replacement when the value changes. + +## Attributes Reference + +In addition to the above, the following attributes are exported: + +* `id` - A string value unique to the resource instance. + +* `output` - The computed value derived from the `input` argument. During a plan where `output` is unknown, it will still be of the same type as `input`. diff --git a/website/layouts/language.erb b/website/layouts/language.erb index 0d5c25e8c4..8c685a9a7f 100644 --- a/website/layouts/language.erb +++ b/website/layouts/language.erb @@ -142,6 +142,10 @@ +
  • + Terraform Data Resource +
  • +