Merge pull request #400 from hashicorp/docs/fix-cv-checks-example

docs: fix cv/check example that doesn't work as expected

Author: ctrombley

website/docs/cloud-docs/workspaces/health.mdx

@@ -109,9 +109,18 @@ You can use one of the following approaches to correct workspace drift:
 
 ## Continuous Validation
 
-Continuous validation will evaluate preconditions, postconditions, and check blocks as part of an assessment, but we recommend using [`check` blocks](/terraform/language/checks) for post-apply monitoring. Use `check` blocks to create custom rules to validate your infrastructure's resources, data sources, and outputs.
+Continuous validation regularly verifies whether your configuration’s custom assertions continue to pass, validating your infrastructure. For example, you can monitor whether your website returns an expected status code, or whether an API gateway certificate is valid. Identifying failed assertions helps you resolve the failure and prevent errors during your next time Terraform operation.
 
-Continuous validation lets Terraform Cloud regularly verify whether your workspace’s custom assertions continue to pass, validating your real-world infrastructure. For example, you can monitor if your website returns an expected status code, or monitor whether an API gateway certificate is valid.
+Continuous validation evaluates preconditions, postconditions, and check blocks as part of an assessment, but we recommend using [check blocks](https://developer.hashicorp.com/terraform/language/checks) for post-apply monitoring. Use check blocks to create custom rules to validate your infrastructure's resources, data sources, and outputs.
+
+### Preventing false positives
+
+Health assessments create a speculative plan to access the current state of your infrastructure. Terraform evaluates any check blocks in your configuration as the last step of creating the speculative plan. If your configuration relies on data sources and the values queried by a data source change between the time of your last run and the assessment, the speculative plan will include those changes. Terraform Cloud will not modify your infrastructure as part of an assessment, but it can use those updated values to evaluate checks. This may lead to false positive results for alerts since your infrastructure did not yet change.
+
+To ensure your checks evaluate the current state of your configuration instead of against a possible future change, use nested data sources that query your actual resource configuration, rather than a computed latest value.
+Refer to the [AMI image
+scenario](#asserting-up-to-date-amis-for-compute-instances) below for an
+example.
 
 Continuous validation alerts you whenever an assertion fails, so you can change your configuration and avoid errors the next time you update infrastructure.
 
@@ -138,9 +147,28 @@ check "health_check" {
 
 Continuous Validation alerts you if the website returns any status code besides `200` while Terraform evaluates this assertion. You can also find failures in your workspace's [Continuous Validation Results](#view-continuous-validation-results) page. You can configure continuous validation alerts in your workspace's [notification settings](/terraform/cloud-docs/workspaces/settings/notifications).
 
+#### Monitoring certificate expiration
+
+[Vault](https://www.vaultproject.io/) lets you secure, store, and tightly control access to tokens, passwords, certificates, encryption keys, and other sensitive data. The following example uses a `check` block to monitor for the expiration of a Vault certificate.
+
+```hcl
+resource "vault_pki_secret_backend_cert" "app" {
+  backend = vault_mount.intermediate.path
+  name = vault_pki_secret_backend_role.test.name
+  common_name = "app.my.domain"
+}
+
+check "certificate_valid" {
+  assert {
+    condition = !vault_pki_secret_backend_cert.app.renew_pending
+    error_message = "Vault cert is ready to renew."
+  }
+}
+```
+
 #### Asserting up-to-date AMIs for compute instances
 
-[HCP Packer](/hcp/docs/packer) stores metadata about your [Packer](https://www.packer.io/) images. The following example postcondition fails when there is a newer AMI version available.
+[HCP Packer](/hcp/docs/packer) stores metadata about your [Packer](https://www.packer.io/) images. The following example check fails when there is a newer AMI version available.
 
 ```hcl
 data "hcp_packer_image" "hashiapp_image" {
@@ -157,34 +185,32 @@ resource "aws_instance" "hashiapp" {
   subnet_id                   = aws_subnet.hashiapp.id
   vpc_security_group_ids      = [aws_security_group.hashiapp.id]
   key_name                    = aws_key_pair.generated_key.key_name
+
+  tags = {
+    Name = "hashiapp"
+  }
 }
 
 check "ami_version_check" {
+  data "aws_instance" "hashiapp_current" {
+    instance_tags = {
+      Name = "hashiapp"
+    }
+  }
+
   assert {
     condition = aws_instance.hashiapp.ami == data.hcp_packer_image.hashiapp_image.cloud_image_id
     error_message = "Must use the latest available AMI, ${data.hcp_packer_image.hashiapp_image.cloud_image_id}."
   }
 }
 ```
 
-#### Monitoring certificate expiration
+In this example, the check block includes a data source that verifies the actual running instance's AMI, rather than the value of the `ami` field in the `aws_instance.hashiapp` resource. If your team publishes a new AMI between the time of the last run and an assessment, this still ensures that the check depends on the actual AMI your instance uses now.
 
-[Vault](https://www.vaultproject.io/) lets you secure, store, and tightly control access to tokens, passwords, certificates, encryption keys, and other sensitive data. The following example uses a `check` block to monitor for the expiration of a Vault certificate.
+Check blocks execute as the last step of a plan or apply after Terraform has planned or provisioned your infrastructure. Each health assessment run performs a speculative plan in its normal course of operation. In practice, this means that check assertions are evaluated against a hypothetical future state where any planned changes have already been applied to the resources under management.
 
-```hcl
-resource "vault_pki_secret_backend_cert" "app" {
-  backend = vault_mount.intermediate.path
-  name = vault_pki_secret_backend_role.test.name
-  common_name = "app.my.domain"
-}
+To evaluate an assertion against the current state of a resource, use a nested data source that is independent from the other resources in your configuration. In the previous example, a data source is used to locate the image provisioned by the `aws_instance.hashiapp` resource. This allows the check to assert against the current image in use, rather than the image that will be used after another round of plan/apply is executed.
 
-check "certificate_valid" {
-  assert {
-    condition = !vault_pki_secret_backend_cert.app.renew_pending
-    error_message = "Vault cert is ready to renew."
-  }
-}
-```
 
 ### View continuous validation results