From 143df6465eef495872aae1dea47af39a61e91106 Mon Sep 17 00:00:00 2001 From: rkoron007 Date: Tue, 21 Oct 2025 10:04:20 -0700 Subject: [PATCH 1/3] New version pinning for OPA --- .../manage-policy-sets/index.mdx | 32 +++++++++++++------ 1 file changed, 22 insertions(+), 10 deletions(-) diff --git a/content/terraform-docs-common/docs/cloud-docs/workspaces/policy-enforcement/manage-policy-sets/index.mdx b/content/terraform-docs-common/docs/cloud-docs/workspaces/policy-enforcement/manage-policy-sets/index.mdx index bba691835e..1d78b3b0b0 100644 --- a/content/terraform-docs-common/docs/cloud-docs/workspaces/policy-enforcement/manage-policy-sets/index.mdx +++ b/content/terraform-docs-common/docs/cloud-docs/workspaces/policy-enforcement/manage-policy-sets/index.mdx @@ -48,7 +48,11 @@ For Sentinel policy sets, using policy evaluations lets you: Policy evaluations **cannot** access cost estimation data, so use policy checks if your policies rely on cost estimates. -~> **Tip:** Sentinel runtime version pinning is supported only for Sentinel 0.23.1 and above, as well as HCP Terraform agent versions 1.13.1 and above + + +Sentinel runtime version pinning is supported by v0.23.1 and above, and HCP Terraform agent versions v1.13.1 and above + + ## Policy enforcement levels @@ -132,7 +136,7 @@ The way you set up and configure a new policy set depends on your workflow and w - For [managed policies](#managed-policies), you use the UI to create a policy set and add managed policies. - For policy sets in a version control system, you use the UI to create a policy set connected to that repository. HCP Terraform automatically refreshes the policy set when you change relevant files in that repository. Version control policy sets have specific organization and formatting requirements. Refer to [Sentinel VCS Repositories](/terraform/cloud-docs/policy-enforcement/sentinel/vcs) and [OPA VCS Repositories](/terraform/cloud-docs/policy-enforcement/opa/vcs) for details. -- For automated workflows like continuous deployment, you can use the UI to create an empty policy set and then use the [Policy Sets API](/terraform/cloud-docs/api-docs/policy-sets) to add policies. You can also use the API or the [`tfe` provider (Sentinel Only)](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/policy_set) to add an entire, packaged policy set. +- For automated workflows like continuous deployment, you can use the UI to create an empty policy set and then use the [Policy Sets API](/terraform/cloud-docs/api-docs/policy-sets) to add policies. You can also use the API or the [`tfe` provider](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/policy_set) to add an entire, packaged policy set. ### Create policy sets @@ -151,9 +155,8 @@ To create a policy set: 1. **(Optional)** Add **Policy exclusions** for this policy set. Specify any workspaces in the policy set's scope that HCP Terraform will not enforce this policy set on. 1. **(Sentinel Only)** Choose a policy set type: - **Standard:** This is the default workflow. A Sentinel policy set uses a [policy check](#policy-checks) in HCP Terraform and lets you access cost estimation data. - - **Agent:** A Sentinel policy set uses a [policy evaluation](#policy-evaluations) in HCP Terraform. This lets you enable policy overrides and enforce a Sentinel runtime version + - **Agent:** A Sentinel policy set uses a [policy evaluation](#policy-evaluations) in HCP Terraform. This lets you enable policy overrides and enforce a Sentinel runtime version. 1. **(OPA Only)** Select a **Runtime version** for this policy set. - 1. **(OPA Only)** Allow **Overrides**, which enables users with override policy permissions to apply plans that have [mandatory policy](#policy-enforcement-levels) failures. 1. **(VCS Only)** Optionally specify the **VCS branch** within your VCS repository where HCP Terraform should import new versions of policies. If you do not set this field, HCP Terraform uses your selected VCS repository's default branch. 1. **(VCS Only)** Specify where your policy set files live using the **Policies path**. This lets you maintain multiple policy sets within a single repository. Use a relative path from your root directory to the directory that contains either the `sentinel.hcl` (Sentinel) or `policies.hcl` (OPA) configuration files. If you do not set this field, HCP Terraform uses the repository's root directory. @@ -161,6 +164,8 @@ To create a policy set: 1. Choose a descriptive and unique **Name** for the policy set. You can use any combination of letters, numbers, `-`, and `_`. 1. Write an optional **Description** that tells other users about the purpose of the policy set and what it contains. +Depending on the type of policy set you choose to create, you can then add policies to the set using the UI, connected VCS repository, the API, or the `tfe` provider. If you are creating an OPA policy set or a Sentinel policy set using agents, we recommend choosing a specific runtime version for your policy set to ensure consistent behavior. + ### Edit policy sets To edit a policy set: @@ -172,20 +177,27 @@ To edit a policy set: ### Evaluate a policy runtime upgrade -You can validate that changing a policy runtime version does not introduce any breaking changes. +For OPA and Sentinel policy sets using agents, we recommend choosing a specific runtime version for your policy set to ensure consistent behavior. -To perform a policy evaluation: + + +HCP Terraform no longer supports the `latest` tag for OPA policy sets. By default, OPA policy sets using the `latest` tag are pinned to v0.61.x. + + + +You can test a new runtime version for a policy set to ensure your policies work as expected before upgrading to that version. To test a new policy set runtime version, perform the following steps: 1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to your organization. 1. Choose **Settings** from the sidebar, then **Policies** in your organization’s settings. 1. Click the policy set you want to upgrade. 1. Click the **Evaluate** tab. -1. Select the **Runtime version** you wish to upgrade to. -1. Select a **Workspace** to test the policy and upgraded version against. +1. Select the **Runtime version** you want to upgrade to. +1. Select a **Workspace** to test the policy set and upgraded version against. 1. Click **Evaluate**. -HCP Terraform will execute the policy set using the specified version and the latest plan data for the selected workspace. It will display the evaluation results. If the evaluation returns a `Failed` status, inspect the JSON output to determine whether the issue is related to a non-compliant resource or is due to a syntax issue. -If the evaluation results in an error, check that the policy configuration is valid. +HCP Terraform executes the policy set using the specified version and the latest plan data for the specified workspace, then displays the evaluation results. If the evaluation returns a `Failed` status, inspect the JSON output to determine if the issue is related to a non-compliant resource or a syntax issue. + +If the evaluation results in an error, check that the policy configuration is valid with your new runtime version. ### Delete policy sets From 41295dfbc6ccb7403623ebf7c216803c46d7c445 Mon Sep 17 00:00:00 2001 From: rkoron007 Date: Tue, 21 Oct 2025 10:11:06 -0700 Subject: [PATCH 2/3] Tell them they can upgrade --- .../workspaces/policy-enforcement/manage-policy-sets/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/terraform-docs-common/docs/cloud-docs/workspaces/policy-enforcement/manage-policy-sets/index.mdx b/content/terraform-docs-common/docs/cloud-docs/workspaces/policy-enforcement/manage-policy-sets/index.mdx index 1d78b3b0b0..e26dfd06e5 100644 --- a/content/terraform-docs-common/docs/cloud-docs/workspaces/policy-enforcement/manage-policy-sets/index.mdx +++ b/content/terraform-docs-common/docs/cloud-docs/workspaces/policy-enforcement/manage-policy-sets/index.mdx @@ -181,7 +181,7 @@ For OPA and Sentinel policy sets using agents, we recommend choosing a specific -HCP Terraform no longer supports the `latest` tag for OPA policy sets. By default, OPA policy sets using the `latest` tag are pinned to v0.61.x. +HCP Terraform no longer supports the `latest` tag for OPA policy sets. By default, OPA policy sets using the `latest` tag are pinned to v0.61.x. To upgrade to a newer OPA runtime version, specify a version in your policy set settings. From 291f4d267a1f71a0ce20ba14941a8f3ce6e76c7d Mon Sep 17 00:00:00 2001 From: rkoron007 Date: Tue, 28 Oct 2025 11:10:50 -0700 Subject: [PATCH 3/3] Tweak phrasing --- .../workspaces/policy-enforcement/manage-policy-sets/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/terraform-docs-common/docs/cloud-docs/workspaces/policy-enforcement/manage-policy-sets/index.mdx b/content/terraform-docs-common/docs/cloud-docs/workspaces/policy-enforcement/manage-policy-sets/index.mdx index e26dfd06e5..c3e924b6cd 100644 --- a/content/terraform-docs-common/docs/cloud-docs/workspaces/policy-enforcement/manage-policy-sets/index.mdx +++ b/content/terraform-docs-common/docs/cloud-docs/workspaces/policy-enforcement/manage-policy-sets/index.mdx @@ -181,7 +181,7 @@ For OPA and Sentinel policy sets using agents, we recommend choosing a specific -HCP Terraform no longer supports the `latest` tag for OPA policy sets. By default, OPA policy sets using the `latest` tag are pinned to v0.61.x. To upgrade to a newer OPA runtime version, specify a version in your policy set settings. +HCP Terraform and Terraform Enterprise no longer supports the `latest` tag for OPA policy sets. By default, OPA policy sets using the `latest` tag are pinned to the most recently supported version. To upgrade to a newer OPA runtime version, specify a version in your policy set settings.