diff --git a/content/terraform/v1.11.x/docs/language/ephemeral/index.mdx b/content/terraform/v1.11.x/docs/language/ephemeral/index.mdx index 8a89c1e76..30c098841 100644 --- a/content/terraform/v1.11.x/docs/language/ephemeral/index.mdx +++ b/content/terraform/v1.11.x/docs/language/ephemeral/index.mdx @@ -1,28 +1,17 @@ --- -page_title: Ephemeral block reference for the Terraform configuration language +page_title: Ephemeral block configuration reference description: Learn to define ephemeral blocks in Terraform configurations to keep temporary and sensitive information out of Terraform state and plan files. --- -# Ephemeral block reference +# Ephemeral block configuration reference -Ephemeral resources are Terraform resources that are essentially temporary. Ephemeral resources have a unique lifecycle, and Terraform does not store them in its state. Each `ephemeral` block describes one or more ephemeral resources, such as a temporary password or connection to another system. +This topic provides reference information for the `ephemeral` block. -> **Note**: Ephemeral resources are available in Terraform v1.10 and later. -## Lifecycle - -The lifecycle of an `ephemeral` resource is different from other resources and data sources. Terraform performs the following lifecycle steps for each ephemeral resource in a configuration: - -1. If Terraform needs to access the result of an ephemeral resource, it opens -that ephemeral resource. For example, if Terraform opens an ephemeral resource for a Vault secret, the Vault provider obtains a lease and returns the secret. +## Introduction -1. If Terraform needs access to the ephemeral resource for longer than the -remote system's enforced expiration time, Terraform asks the provider -to periodically renew it. For example, if Terraform renews a Vault secret `ephemeral` resource, the Vault provider calls Vault's lease renewal API endpoint to extend the expiration time. - -1. Once Terraform no longer needs an ephemeral resource, Terraform closes -it. This happens after the providers that depend on an ephemeral resource -complete all of their work for the current Terraform run phase. For example, closing a Vault secret ephemeral resource means the Vault provider explicitly ends the lease, allowing Vault to immediately revoke the associated credentials. +Ephemeral resources are Terraform resources that are essentially temporary. Ephemeral resources have a unique lifecycle, and Terraform does not store them in its state. Each `ephemeral` block describes one or more ephemeral resources, such as a temporary password or connection to another system. ## Dependency graph @@ -64,9 +53,9 @@ ephemeral resources: * In a [write-only argument](/terraform/language/resources/ephemeral/write-only) * In another ephemeral resource -* In [local values](/terraform/language/values/locals#ephemeral-values) -* In [ephemeral variables](/terraform/language/values/variables#exclude-values-from-state) -* In [ephemeral outputs](/terraform/language/values/outputs#ephemeral-avoid-storing-values-in-state-or-plan-files) +* In [local values](/terraform/language/block/locals) +* In [ephemeral variables](/terraform/language/block/variable#ephemeral) +* In [ephemeral outputs](/terraform/language/block/output#ephemeral) * Configuring providers in the `provider` block * In [provisioner](/terraform/language/resources/provisioners/syntax) and [connection](/terraform/language/resources/provisioners/connection) blocks diff --git a/content/terraform/v1.12.x/data/language-nav-data.json b/content/terraform/v1.12.x/data/language-nav-data.json index 4e0a47a18..95ac8bd6c 100644 --- a/content/terraform/v1.12.x/data/language-nav-data.json +++ b/content/terraform/v1.12.x/data/language-nav-data.json @@ -211,8 +211,8 @@ "routes": [ { "title": "Overview", "path": "values" }, { "title": "Input Variables", "path": "values/variables" }, - { "title": "Output Values", "path": "values/outputs" }, - { "title": "Local Values", "path": "values/locals" } + { "title": "Output block", "href": "/terraform/language/block/output" }, + { "title": "Locals block", "href": "/terraform/language/block/locals" } ] }, { @@ -336,7 +336,13 @@ } ] }, - { "title": "Checks", "path": "checks" }, + { "title": "Check block", "href": "/terraform/language/block/check" }, + { + "title": "Testing and Validation", + "routes": [ + { "title": "Validate your configuration", "path": "test-and-validate/validate" } + ] + }, { "title": "Import", "routes": [ @@ -379,10 +385,6 @@ "title": "Dynamic Blocks", "path": "expressions/dynamic-blocks" }, - { - "title": "Custom Conditions", - "path": "expressions/custom-conditions" - }, { "title": "Type Constraints", "path": "expressions/type-constraints" @@ -1117,5 +1119,47 @@ "path": "v1-compatibility-promises" }, { "divider": true }, + { "heading": "REFERENCE" }, + { + "title": "Configuration blocks", + "routes": [ + { + "title": "check", + "path": "block/check" + }, + { + "title": "data", + "path": "block/data" + }, + { + "title": "locals", + "path": "block/locals" + }, + { + "title": "moved", + "path": "block/moved" + }, + { + "title": "output", + "path": "block/output" + }, + { + "title": "removed", + "path": "block/removed" + }, + { + "title": "resource", + "path": "block/resource" + }, + { + "title": "terraform", + "path": "block/terraform" + }, + { + "title": "variable", + "path": "block/variable" + } + ] + }, { "title": "Terraform Internals", "href": "/internals" } ] diff --git a/content/terraform/v1.12.x/docs/cli/commands/import.mdx b/content/terraform/v1.12.x/docs/cli/commands/import.mdx index c3097e739..003a392b6 100644 --- a/content/terraform/v1.12.x/docs/cli/commands/import.mdx +++ b/content/terraform/v1.12.x/docs/cli/commands/import.mdx @@ -67,11 +67,11 @@ The command-line flags are all optional. The following flags are available: can be set multiple times. Variable values are interpreted as [literal expressions](/terraform/language/expressions/types) in the Terraform language, so list and map values can be specified via this flag. - + - `-var-file=foo` - Set variables in the Terraform configuration from - a [variable file](/terraform/language/values/variables#variable-definitions-tfvars-files). If + a [variable file](/terraform/language/block/variable#variable-definitions-tfvars-files). If `terraform.tfvars` or any `.auto.tfvars` files are present in the current - directory, they are automatically loaded. Terraform loads `terraform.tfvars` + directory, they are automatically loaded. Terraform loads `terraform.tfvars` first and the `.auto.tfvars` files after in alphabetical order. Any files specified by `-var-file` override any values set automatically from files in the working directory. This flag can be used multiple times. This is only diff --git a/content/terraform/v1.12.x/docs/cli/commands/plan.mdx b/content/terraform/v1.12.x/docs/cli/commands/plan.mdx index 7cbbcf6fa..770c1d2e0 100644 --- a/content/terraform/v1.12.x/docs/cli/commands/plan.mdx +++ b/content/terraform/v1.12.x/docs/cli/commands/plan.mdx @@ -5,10 +5,10 @@ description: >- changes that Terraform will make to your infrastructure. --- -# `terraform plan` command +# `terraform plan` command The `terraform plan` command creates an execution plan, which lets you preview -the changes that Terraform plans to make to your infrastructure. +the changes that Terraform plans to make to your infrastructure. ## Introduction By default, Terraform performs the following operations when it creates a plan: @@ -138,25 +138,25 @@ In addition to alternate [planning modes](#planning-modes), there are several op -> **Note:** Use `-target=ADDRESS` in exceptional circumstances only, such as recovering from mistakes or working around Terraform limitations. Refer to [Resource Targeting](#resource-targeting) for more details. - `-var 'NAME=VALUE'` - Sets a value for a single - [input variable](/terraform/language/values/variables) declared in the + [input variable](/terraform/language/block/variable) declared in the root module of the configuration. Use this option multiple times to set more than one variable. Refer to [Input Variables on the Command Line](#input-variables-on-the-command-line) for more information. - + - `-var-file=FILENAME` - Sets values for potentially many - [input variables](/terraform/language/values/variables) declared in the + [input variables](/terraform/language/block/variable) declared in the root module of the configuration, using definitions from a - ["tfvars" file](/terraform/language/values/variables#variable-definitions-tfvars-files). + ["tfvars" file](/terraform/language/block/variable#variable-definitions-tfvars-files). Use this option multiple times to include values from more than one file. - + There are several other ways to set values for input variables in the root module, aside from the `-var` and `-var-file` options. Refer to -[Assigning Values to Root Module Variables](/terraform/language/values/variables#assigning-values-to-root-module-variables) for more information. +[Assigning Values to Root Module Variables](/terraform/language/block/variable#assigning-values-to-root-module-variables) for more information. ### Input Variables on the Command Line You can use the `-var` command line option to specify values for -[input variables](/terraform/language/values/variables) declared in your +[input variables](/terraform/language/block/variable) declared in your root module. However, to do so will require writing a command line that is parsable both @@ -222,10 +222,11 @@ terraform plan -var 'name=["a", "b", "c"]' terraform plan -var "name=[\"a\", \"b\", \"c\"]" ``` + Similar constraints apply when setting input variables using environment variables. For more information on the various methods for setting root module input variables, see -[Assigning Values to Root Module Variables](/terraform/language/values/variables#assigning-values-to-root-module-variables). +[Assigning Values to Root Module Variables](/terraform/language/block/variable#assigning-values-to-root-module-variables). ### Resource Targeting diff --git a/content/terraform/v1.12.x/docs/cli/config/environment-variables.mdx b/content/terraform/v1.12.x/docs/cli/config/environment-variables.mdx index 70144c6fd..69c3b3565 100644 --- a/content/terraform/v1.12.x/docs/cli/config/environment-variables.mdx +++ b/content/terraform/v1.12.x/docs/cli/config/environment-variables.mdx @@ -1,7 +1,7 @@ --- page_title: Terraform CLI environment variables reference description: >- - Terraform environment variables let you customize the Terraform CLI's default behavior. + Terraform environment variables let you customize the Terraform CLI's default behavior. Learn about the Terraform CLI environment variables. --- @@ -61,7 +61,8 @@ export TF_VAR_alist='[1,2,3]' export TF_VAR_amap='{ foo = "bar", baz = "qux" }' ``` -For more on how to use `TF_VAR_name` in context, check out the section on [Variable Configuration](/terraform/language/values/variables). + +For more on how to use `TF_VAR_name` in context, check out the section on [Variable Configuration](/terraform/language/block/variable). ## TF_CLI_ARGS and TF_CLI_ARGS_name diff --git a/content/terraform/v1.12.x/docs/cli/inspect/index.mdx b/content/terraform/v1.12.x/docs/cli/inspect/index.mdx index cd323c172..63c1d2f73 100644 --- a/content/terraform/v1.12.x/docs/cli/inspect/index.mdx +++ b/content/terraform/v1.12.x/docs/cli/inspect/index.mdx @@ -1,5 +1,5 @@ --- -page_title: Inspect infrastructure +page_title: Inspect infrastructure description: >- The terraform inspect commands return dependency information and outputs. Learn how to use terraform inspect commands to understand your infrastructure. @@ -20,7 +20,7 @@ or just to gain a deeper or more holistic understanding of your infrastructure. - [The `terraform graph` command](/terraform/cli/commands/graph) creates a visual representation of a configuration or a set of planned changes. - [The `terraform output` command](/terraform/cli/commands/output) can get the - values for the top-level [output values](/terraform/language/values/outputs) of + values for the top-level [output values](/terraform/language/block/output) of a configuration, which are often helpful when making use of the infrastructure Terraform has provisioned. - [The `terraform show` command](/terraform/cli/commands/show) can generate diff --git a/content/terraform/v1.12.x/docs/cli/test/index.mdx b/content/terraform/v1.12.x/docs/cli/test/index.mdx index 08177edce..564e1ef22 100644 --- a/content/terraform/v1.12.x/docs/cli/test/index.mdx +++ b/content/terraform/v1.12.x/docs/cli/test/index.mdx @@ -1,5 +1,5 @@ --- -page_title: Testing features in Terraform +page_title: Testing features in Terraform description: >- Learn about the terraform test command, which runs structured tests and validations for your configuration to ensure correctness in your infrastructure. @@ -13,14 +13,14 @@ This topic provides an overview of the testing features in Terraform to help you Terraform provides the following types of testing capabilities: -1. Configuration and infrastructure validation as part of your regular Terraform operations. Refer to [Custom Conditions](/terraform/language/expressions/custom-conditions) and [Checks](/terraform/language/checks) to learn more about these types of testing capabilities. +1. Configuration and infrastructure validation as part of your regular Terraform operations. Refer to [Validate your configuration](/terraform/language/test-and-validate/validate) to learn more. 1. Traditional unit and integration testing on your configuration. Refer to the [`terraform test` command](/terraform/cli/commands/test) documentation to learn more about this testing capability. -### Additional testing and validation features +### Additional testing and validation features -- [Input Variable Validation](/terraform/language/expressions/custom-conditions#input-variable-validation) -- [Pre and Post-conditions](/terraform/language/expressions/custom-conditions#preconditions-and-postconditions) -- [Checks](/terraform/language/checks) +- [Input Variable Validation](/terraform/language/test-and-validate/validate#input-variable-validation) +- [Preconditions and postconditions](/terraform/language/test-and-validate/validate#preconditions-and-postconditions) +- [Checks](/terraform/language/block/check) ## How the `terraform test` command works @@ -41,14 +41,14 @@ Terraform test files [have their own configuration syntax](/terraform/language/t Validations allow you to verify aspects of your configuration and infrastructure as it is applied and created. HCP Terraform also supports automated [continuous validation](/terraform/cloud-docs/workspaces/health#continuous-validation). -The Terraform `test` command also executes any validations within your configuration as part of the tests it executes. For more information on the available validation, refer to [Checks](/terraform/language/checks) and [Custom Conditions](/terraform/language/expressions/custom-conditions). +The Terraform `test` command also executes any validations within your configuration as part of the tests it executes. Refer to [Validate your configuration](/terraform/language/test-and-validate/validate) to learn more. ## Tests versus validations You can write many validations as test assertions, but there are specific use cases for both. -Validations are executed during Terraform plan and apply operations, and the Terraform `test` command also runs validations while executing tests. Therefore, use validations to validate aspects of your configuration that should always be true and could impact the valid execution of your infrastructure. +Terraform executes validations during plan and apply operations and when you run the `terraform test` command. Therefore, use validations to validate aspects of your configuration that should always be true and could impact the valid execution of your infrastructure. Module authors should note that validations are executed and exposed to module users, so if they fail, ensure the failure messages are understandable and actionable. -In contrast, Terraform only executes tests when you run `terraform test`. Use tests to assert the correctness of any logical operations or specific behavior within your configuration. For example, you can test that Terraform creates conditional resources based on an input by setting the input controlling those resources to a certain value then verifying the resources Terraform creates. \ No newline at end of file +By contrast, Terraform only executes tests when you run `terraform test`. Use tests to assert the correctness of any logical operations or specific behavior within your configuration. For example, you can test that Terraform creates conditional resources based on an input by setting the input controlling those resources to a certain value then verifying the resources Terraform creates. diff --git a/content/terraform/v1.12.x/docs/cli/workspaces/index.mdx b/content/terraform/v1.12.x/docs/cli/workspaces/index.mdx index 3baca17bd..3252ce8d2 100644 --- a/content/terraform/v1.12.x/docs/cli/workspaces/index.mdx +++ b/content/terraform/v1.12.x/docs/cli/workspaces/index.mdx @@ -21,7 +21,7 @@ Use the [`terraform workspace list`](/terraform/cli/commands/workspace/list), [` Use [the `terraform workspace select` command](/terraform/cli/commands/workspace/select) to change the currently selected workspace. For a given working directory, you can only select one workspace at a time. Most Terraform commands only interact with the currently selected workspace. This includes [provisioning](/terraform/cli/run) and [state manipulation](/terraform/cli/state). -When you provision infrastructure in each workspace, you usually need to manually specify different [input variables](/terraform/language/values/variables) to differentiate each collection. For example, you might deploy test infrastructure to a different region. +When you provision infrastructure in each workspace, you usually need to manually specify different [input variables](/terraform/language/block/variable) to differentiate each collection. For example, you might deploy test infrastructure to a different region. ## Use Cases diff --git a/content/terraform/v1.12.x/docs/language/block/check.mdx b/content/terraform/v1.12.x/docs/language/block/check.mdx new file mode 100644 index 000000000..828dc56fd --- /dev/null +++ b/content/terraform/v1.12.x/docs/language/block/check.mdx @@ -0,0 +1,235 @@ +--- +page_title: check block reference for the Terraform configuration language +description: How to use the `check` block to validate infrastructure outside of the usual resource lifecycle. +--- + +# `check` block reference + +Use the `check` block to validate your infrastructure outside of the typical resource lifecycle. + +Terraform executes the `check` block as the last step of plan or apply operation, after Terraform has planned or provisioned your infrastructure. When a `check` block's assertion fails, Terraform reports a warning and continues executing the current operation. + +## Background + +Terraform evaluates `check` blocks locally whenever you plan or apply your configuration. In HCP Terraform, you can enable health checks on a workspace to automatically and continuously execute checks defined in that workspace's configuration. Refer to [Continuous validation](/terraform/cloud-docs/workspaces/health#continuous-validation) for details. + +The `check` block is one of the ways you can validate your configuration. Checks contain assertions, which specify the condition that Terraform is verifying during that check. Other validations run during other stages of a Terraform operation, and can block operations if they fail. The `check` block is the only validation that does not block operations, if a `check` block's assertion fails, Terraform reports a warning and continues executing the current operation. + +For information on all of the ways to validation configuration in Terraform, refer to [Validate your configuration](/terraform/language/test-and-validate/validate#input-variable-validation). + +## Configuration model + +The `check` block supports the following arguments: + +- [`check "