diff --git a/website/data/language-nav-data.json b/website/data/language-nav-data.json index 06b7b94b65a7..f5a255621f7f 100644 --- a/website/data/language-nav-data.json +++ b/website/data/language-nav-data.json @@ -6,9 +6,9 @@ "path": "attr-as-blocks", "hidden": true }, - { - "title": "Style Guide", - "path": "style" + { + "title": "Style Guide", + "path": "style" }, { "title": "Stacks", @@ -211,7 +211,7 @@ "routes": [ { "title": "Overview", "path": "values" }, { "title": "Input Variables", "path": "values/variables" }, - { "title": "Output Values", "path": "values/outputs" }, + { "title": "Output block", "href": "/terraform/language/block/output" }, { "title": "Local Values", "path": "values/locals" } ] }, @@ -273,11 +273,11 @@ }, { "title": "Moved block", - "path": "moved" + "href": "/terraform/language/block/moved" }, { "title": "Terraform block", - "path": "terraform" + "href": "/terraform/language/block/terraform" }, { "title": "Backend block", @@ -332,7 +332,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": [ @@ -375,10 +381,6 @@ "title": "Dynamic Blocks", "path": "expressions/dynamic-blocks" }, - { - "title": "Custom Conditions", - "path": "expressions/custom-conditions" - }, { "title": "Type Constraints", "path": "expressions/type-constraints" @@ -1109,5 +1111,32 @@ "path": "v1-compatibility-promises" }, { "divider": true }, + { "heading": "REFERENCE" }, + { + "title": "Configuration blocks", + "routes": [ + { + "title": "resource", + "path": "block/resource" + }, + { + "title": "check", + "path": "block/check" + }, + { + "title": "Moved block", + "path": "block/moved" + }, + { + "title": "Output block", + "path": "block/output" + }, + { + "title": "Terraform block", + "path": "block/terraform" + } + ] + }, + { "divider": true }, { "title": "Terraform Internals", "href": "/internals" } ] diff --git a/website/docs/cli/inspect/index.mdx b/website/docs/cli/inspect/index.mdx index cd323c1724b1..63c1d2f73d86 100644 --- a/website/docs/cli/inspect/index.mdx +++ b/website/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/website/docs/cli/test/index.mdx b/website/docs/cli/test/index.mdx index 08177edce984..564e1ef22b7c 100644 --- a/website/docs/cli/test/index.mdx +++ b/website/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/website/docs/language/block/check.mdx b/website/docs/language/block/check.mdx new file mode 100644 index 000000000000..235af6acb627 --- /dev/null +++ b/website/docs/language/block/check.mdx @@ -0,0 +1,236 @@ +--- +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/mitigate-risk/validate#input-variable-validation). + +## Configuration model + +The `check` block supports the following arguments: + +- [`check "