Skip to content

Latest commit

 

History

History
285 lines (237 loc) · 11.2 KB

policy-evaluations.mdx

File metadata and controls

285 lines (237 loc) · 11.2 KB
Raw
page_title description
Policy Evaluations - API Docs - HCP Terraform
Use the `/policy-evaluations` endpoint to manage the Sentinel and OPA policy evaluations performed on a Terraform run. List and show policy outcomes and list policy evaluations using the HTTP API.

Policy Evaluations API

Policy evaluations are run within the HCP Terraform 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

Parameter Description
:task_stage_id The task stage ID to get.
Status Response Reason
200 JSON API document Success
404 JSON API error object Task 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.

Parameter Description
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

Parameter Description
:policy_evaluation_id The 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.

Status Response Reason
200 JSON API document Success
404 JSON API error object Policy 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.

Parameter Description
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

Parameter Description
:policy_set_outcome_id The ID of the policy outcome to show. Refer to List the Policy Outcomes for reference information about finding IDs.
Status Response Reason
200 JSON API document The request was successful
404 JSON API error object Policy 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"
            }
         }
      }
   }
}