docs terraform output does not match actual and does not show CI

[qmg-lpicquet]

Hi, I'm new to OPA and I am not getting the desired outcome from it just yet.

On the https://www.openpolicyagent.org/docs/latest/terraform/ page,
When I run the opa exec command, I do not get the one word "true" output, instead I get a json.

I would also expect the opa command line tool to return a non-zero exit code when the policy fails.
I added the --fail parameter, to no effect and the --fail-defined and --fail-non-empty fail even when the policy checks pass. Clearly I do not understand those parameters and their intended behaviour.

So my question are:

• can the --fail, --fail-defined and --fail-non-empty parameters be showcased with examples so that we can understand them better?
• can the terraform example be updated to show the correct output?

[charlieegan3]

Hey, in #7429 I have made a few updates to the terraform docs page you have been having issues with. I hope it'll be clearer for users in the future now.

In OPA's exec command, the --fail flag causes the command to exit with a non-zero code for undefined results, --fail-defined inverts this behavior by exiting with non-zero code for defined results, and --fail-non-empty exits with non-zero code when results are non-empty arrays.

Might some examples like this have helped? or did you have something else in mind?

example file:

…/opa update-tf-docs ➜ cat foo/foo.rego
   1   │ package foo
   2   │
   3   │ truth := true
   4   │
   5   │ falsehood := false
   6   │
   7   │ list_empty := []
   8   │
   9   │ list := [1, 2, 3]

--fail with true result == 0 exit code.

…/opa update-tf-docs ➜ opa exec --decision 'foo/truth' --bundle ./foo input.json --fail; echo $?
{
  "result": [
    {
      "path": "input.json",
      "result": true
    }
  ]
}
0

--fail with false result == 0 exit code as well.

…/opa update-tf-docs ➜ opa exec --decision 'foo/falsehood' --bundle ./foo input.json --fail; echo $?
{
  "result": [
    {
      "path": "input.json",
      "result": false
    }
  ]
}
0

--fail with undefined result == 1 exit code and error message.

…/opa update-tf-docs ➜ opa exec --decision 'foo/undefined' --bundle ./foo input.json --fail; echo $?
{
  "result": [
    {
      "path": "input.json",
      "error": {
        "code": "opa_undefined_error",
        "message": "foo/undefined decision was undefined"
      }
    }
  ]
}
{"err":"exec error: there were 0 failures and 1 errors counted in the results list, and --fail is set","level":"error","msg":"Unexpected error.","time":"2025-03-06T18:16:45+01:00"}
1

--fail-defined with true result, == 1 exit code.

…/opa update-tf-docs ➜ opa exec --decision 'foo/truth' --bundle ./foo input.json --fail-defined; echo $?
{
  "result": [
    {
      "path": "input.json",
      "result": true
    }
  ]
}
{"err":"exec error: there were 1 failures and 0 errors counted in the results list, and --fail-defined is set","level":"error","msg":"Unexpected error.","time":"2025-03-06T18:17:00+01:00"}
1

--fail-defined with undefined result, == 0 exit code.

…/opa update-tf-docs ➜ opa exec --decision 'foo/undefined' --bundle ./foo input.json --fail-defined; echo $?
{
  "result": [
    {
      "path": "input.json",
      "error": {
        "code": "opa_undefined_error",
        "message": "foo/undefined decision was undefined"
      }
    }
  ]
}
0

--fail-non-empty with undefined == 0 exit.

…/opa update-tf-docs ➜ opa exec --decision 'foo/undefined' --bundle ./foo input.json --fail-non-empty; echo $?
{
  "result": [
    {
      "path": "input.json",
      "error": {
        "code": "opa_undefined_error",
        "message": "foo/undefined decision was undefined"
      }
    }
  ]
}
0

--fail-non-empty non empty list with == 1.

…/opa update-tf-docs ➜ opa exec --decision 'foo/list' --bundle ./foo input.json --fail-non-empty; echo $?
{
  "result": [
    {
      "path": "input.json",
      "result": [
        1,
        2,
        3
      ]
    }
  ]
}
{"err":"exec error: there were 1 failures and 0 errors counted in the results list, and --fail-non-empty is set","level":"error","msg":"Unexpected error.","time":"2025-03-06T18:17:51+01:00"}
1

--fail-non-empty with empty == 0 exit code.

…/opa update-tf-docs ➜ opa exec --decision 'foo/list_empty' --bundle ./foo input.json --fail-non-empty; echo $?
{
  "result": [
    {
      "path": "input.json",
      "result": []
    }
  ]
}
0