HashiCorp Developer AI Private beta now available Sign up today
Terraform
Terraform Home

You are viewing documentation for version v202402-2. View latest version.

Policy Evaluations API

Policy evaluations are run within the Terraform Cloud agents in HCP Terraform's infrastructure. Policy evaluations do not have access to cost estimation data. This set of APIs provides endpoints to list and get policy evaluations and policy outcomes.

List Policy Evaluations in the Task Stage

Each run passes through several stages of action (pending, plan, policy check, apply, and completion), and shows the progress through those stages as run states. This endpoint allows you to list policy evaluations that are part of the task stage.

GET /task-stages/:task_stage_id/policy-evaluations

ParameterDescription
:task_stage_idThe task stage ID to get.
StatusResponseReason
200JSON API documentSuccess
404JSON API error objectTask stage not found

Query Parameters

This endpoint supports pagination with standard URL query parameters. Remember to percent-encode [ as %5B and ] as %5D if your tooling does not automatically encode URLs.

ParameterDescription
page[number]Optional. If omitted, the endpoint returns the first page.
page[size]Optional. If omitted, the endpoint returns 20 agent pools per page.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/task-stages/ts-rL5ZsuwfjqfPJcdi/policy-evaluations

Sample Response

{
   "data":[
      {
         "id":"poleval-8Jj9Hfoz892D9WMX",
         "type":"policy-evaluations",
         "attributes":{
            "status":"passed",
            "policy-kind":"opa",
            "policy-tool-version": "0.44.0",
            "result-count": {
              "advisory-failed":0,
              "errored":0,
              "mandatory-failed":0,
              "passed":1
            }
            "status-timestamps":{
               "passed-at":"2022-09-16T01:40:30+00:00",
               "queued-at":"2022-09-16T01:40:04+00:00",
               "running-at":"2022-09-16T01:40:08+00:00"
            },
            "created-at":"2022-09-16T01:39:07.782Z",
            "updated-at":"2022-09-16T01:40:30.010Z"
         },
         "relationships":{
            "policy-attachable":{
               "data":{
                  "id":"ts-yxskot8Gz5yHa38W",
                  "type":"task-stages"
               }
            },
            "policy-set-outcomes":{
               "links":{
                  "related":"/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX/policy-set-outcomes"
               }
            }
         },
         "links":{
            "self":"/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX"
         }
      }
   ]
}

List Policy Outcomes

GET /policy-evaluations/:policy_evaluation_id/policy-set-outcomes

ParameterDescription
:policy_evaluation_idThe ID of the policy evaluation the outcome belongs to get

This endpoint allows you to list policy set outcomes that are part of the policy evaluation.

StatusResponseReason
200JSON API documentSuccess
404JSON API error objectPolicy evaluation not found

Query Parameters

This endpoint supports pagination with standard URL query parameters. Remember to percent-encode [ as %5B and ] as %5D if your tooling does not automatically encode URLs.

ParameterDescription
page[number]Optional. If omitted, the endpoint returns the first page.
page[size]Optional. If omitted, the endpoint returns 20 policy sets per page.
filter[n][status]Optional. If omitted, the endpoint returns all policies regardless of status. Must be either "passed", "failed", or "errored".
filter[n][enforcementLevel]Optional. Only used if paired with a non-errored status filter. Must be either "advisory" or "mandatory."

Note: You can use filter[n] to combine combinations of statuses and enforcement levels. Policy outcomes with an errored status do not have an enforcement level.

Sample Request

The following example requests demonstrate how to call the policy-set-outcomes endpoint using cuRL.

All Policy Outcomes

The following example call returns all policy set outcomes.

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX/policy-set-outcomes

Failed and Errored Policy Outcomes

The following example call filters the response so that it only contains failed outcomes and errors.

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX/policy-set-outcomes?filter[0][status]=errored&filter[1][status]=failed&filter[1][enforcementLevel]=mandatory

Sample Response

The following example response shows that the policyVCS policy failed.

{
   "data":[
      {
         "id":"psout-cu8E9a97LBepZZXd",
         "type":"policy-set-outcomes",
         "attributes":{
            "outcomes":[
               {
                  "enforcement_level":"advisory",
                  "query":"data.terraform.main.main",
                  "status":"failed",
                  "policy_name":"policyVCS",
                  "description":""
               }
            ],
            "error":"",
            "overridable":true,
            "policy-set-name":"opa-policies-vcs",
            "policy-set-description":null,
            "result-count":{
               "advisory-failed":1,
               "errored":0,
               "mandatory-failed":0,
               "passed":0
            },
            "policy-tool-version": "0.54.0"
         },
         "relationships":{
            "policy-evaluation":{
               "data":{
                  "id":"poleval-8Jj9Hfoz892D9WMX",
                  "type":"policy-evaluations"
               }
            }
         }
      }
   ],
   "links":{
      "self":"/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX/policy-set-outcomes?page%5Bnumber%5D=1\u0026page%5Bsize%5D=20",
      "first":"/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX/policy-set-outcomes?page%5Bnumber%5D=1\u0026page%5Bsize%5D=20",
      "prev":null,
      "next":null,
      "last":"/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX/policy-set-outcomes?page%5Bnumber%5D=1\u0026page%5Bsize%5D=20"
   },
   "meta":{
      "pagination":{
         "current-page":1,
         "page-size":20,
         "prev-page":null,
         "next-page":null,
         "total-pages":1,
         "total-count":1
      }
   }
}

Show a Policy Outcome

GET /policy-set-outcomes/:policy_set_outcome_id

ParameterDescription
:policy_set_outcome_idThe ID of the policy outcome to show. Refer to List the Policy Outcomes for reference information about finding IDs.
StatusResponseReason
200JSON API documentThe request was successful
404JSON API error objectPolicy set outcome not found or user unauthorized to perform action

Sample Request

The following example request gets the outcomes for the psout-cu8E9a97LBepZZXd policy set.

curl --request GET \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/policy-set-outcomes/psout-cu8E9a97LBepZZXd

Sample Response

The following example response shows that the policyVCS policy failed.

{
   "data":{
      "id":"psout-cu8E9a97LBepZZXd",
      "type":"policy-set-outcomes",
      "attributes":{
         "outcomes":[
            {
               "enforcement_level":"advisory",
               "query":"data.terraform.main.main",
               "status":"failed",
               "policy_name":"policyVCS",
               "description":""
            }
         ],
         "error":"",
         "overridable":true,
         "policy-set-name":"opa-policies-vcs",
         "policy-set-description":null,
         "result-count":{
            "advisory-failed":1,
            "errored":0,
            "mandatory-failed":0,
            "passed":0
         },
         "policy-tool-version": "0.54.0"
      },
      "relationships":{
         "policy-evaluation":{
            "data":{
               "id":"poleval-8Jj9Hfoz892D9WMX",
               "type":"policy-evaluations"
            }
         }
      }
   }
}