Merge pull request #694 from hashicorp/mr/TF-1451-docs

Add Documentation : OPA support for policies and policy sets

docs/testing.md

@@ -27,7 +27,7 @@ To run all tests, you will need to set the following environment variables:
 
 ##### Required:
 A hostname and token must be provided in order to run the acceptance tests. By
-default, these are loaded from the the `credentials` in the [CLI config
+default, these are loaded from the `credentials` in the [CLI config
 file](https://www.terraform.io/docs/commands/cli-config.html). You can override
 these values with the environment variables specified below:
 

website/docs/d/policy_set.html.markdown

@@ -35,6 +35,8 @@ The following arguments are supported:
 * `name` - Name of the policy set.
 * `description` - Description of the policy set.
 * `global` - Whether or not the policy set applies to all workspaces in the organization.
+* `kind` - The policy-as-code framework for the policy. Valid values are "sentinel" and "opa".
+* `overridable` - Whether users can override this policy when it fails during a run. Only valid for OPA policies.
 * `workspace_ids` - IDs of the workspaces that use the policy set.
 * `policy_ids` - IDs of the policies attached to the policy set.
 * `policies_path` - The sub-path within the attached VCS repository when using `vcs_repo`.

website/docs/r/policy.html.markdown

@@ -0,0 +1,76 @@
+---
+layout: "tfe"
+page_title: "Terraform Enterprise: tfe_policy"
+sidebar_current: "docs-resource-tfe-policy"
+description: |-
+  Manages policies.
+---
+
+# tfe_policy
+
+Policies are rules enforced on Terraform runs. You can use policies to validate that the Terraform plan complies with security rules and best practices.
+Two policy-as-code frameworks are integrated with Terraform Enterprise: Sentinel and Open Policy Agent (OPA).
+
+Policies are configured on a per-organization level and are organized and
+grouped into policy sets, which define the workspaces on which policies are
+enforced during runs.
+
+
+## Example Usage
+
+Basic usage for Sentinel:
+
+```hcl
+resource "tfe_policy" "test" {
+  name         = "my-policy-name"
+  description  = "This policy always passes"
+  organization = "my-org-name"
+  kind         = "sentinel"
+  policy       = "main = rule { true }"
+  enforce_mode = "hard-mandatory"
+}
+```
+
+Basic usage for Open Policy Agent(OPA):
+
+```hcl
+resource "tfe_policy" "test" {
+  name         = "my-policy-name"
+  description  = "This policy always passes"
+  organization = "my-org-name"
+  kind         = "opa"
+  policy       = "package example rule[\"not allowed\"] { false }"
+  query        = "data.example.rule"
+  enforce_mode = "mandatory"
+}
+```
+
+## Argument Reference
+
+The following arguments are supported:
+
+* `name` - (Required) Name of the policy.
+* `description` - (Optional) A description of the policy's purpose.
+* `organization` - (Required) Name of the organization.
+* `kind` - (Optional) The policy-as-code framework associated with the policy.
+   Defaults to `sentinel` if not provided. Valid values are `sentinel` and `opa`. 
+* `query` - (Optional) The OPA query to identify a specific policy rule that 
+   needs to run within your Rego code. Required for all OPA policies. 
+* `policy` - (Required) The actual policy itself.
+* `enforce_mode` - (Required) The enforcement level of the policy. Valid
+  values for Sentinel are `advisory`, `hard-mandatory` and `soft-mandatory`. Defaults
+  to `soft-mandatory`. Valid values for OPA are `advisory` and `mandatory`. Defaults
+  to `advisory`.
+
+## Attributes Reference
+
+* `id` - The ID of the policy.
+
+## Import
+
+Policies can be imported; use `<ORGANIZATION NAME>/<POLICY ID>` as the
+import ID. For example:
+
+```shell
+terraform import tfe_policy.test my-org-name/pol-wAs3zYmWAhYK7peR
+```

website/docs/r/policy_set.html.markdown

@@ -8,8 +8,8 @@ description: |-
 
 # tfe_policy_set
 
-Sentinel Policy as Code is an embedded policy as code framework integrated
-with Terraform Enterprise.
+Policies are rules enforced on Terraform runs. Two policy-as-code frameworks are 
+integrated with Terraform Enterprise: Sentinel and Open Policy Agent (OPA).
 
 Policy sets are groups of policies that are applied together to related workspaces.
 By using policy sets, you can group your policies by attributes such as environment
@@ -25,6 +25,7 @@ resource "tfe_policy_set" "test" {
   name          = "my-policy-set"
   description   = "A brand new policy set"
   organization  = "my-org-name"
+  kind          = "sentinel"
   policies_path = "policies/my-policy-set"
   workspace_ids = [tfe_workspace.test.id]
 
@@ -44,6 +45,7 @@ resource "tfe_policy_set" "test" {
   name          = "my-policy-set"
   description   = "A brand new policy set"
   organization  = "my-org-name"
+  kind          = "sentinel"
   policy_ids    = [tfe_sentinel_policy.test.id]
   workspace_ids = [tfe_workspace.test.id]
 }
@@ -77,6 +79,11 @@ The following arguments are supported:
 * `global` - (Optional) Whether or not policies in this set will apply to
   all workspaces. Defaults to `false`. This value _must not_ be provided if
   `workspace_ids` is provided.
+* `kind` - (Optional) The policy-as-code framework associated with the policy.
+   Defaults to `sentinel` if not provided. Valid values are `sentinel` and `opa`.
+   A policy set can only have policies that have the same underlying kind.
+* `overridable` - (Optional) Whether or not users can override this policy when 
+   it fails during a run. Defaults to `false`. Only valid for OPA policies. 
 * `organization` - (Required) Name of the organization.
 * `policies_path` - (Optional) The sub-path within the attached VCS repository
   to ingress when using `vcs_repo`. All files and directories outside of this

website/tfe.erb

@@ -98,6 +98,10 @@
                             <a href="/docs/providers/tfe/r/run_trigger.html">tfe_run_trigger</a>
                         </li>
 
+                        <li<%= sidebar_current("docs-resource-tfe-policy") %>>
+                            <a href="/docs/providers/tfe/r/policy.html">tfe_policy</a>
+                        </li>
+
                         <li<%= sidebar_current("docs-resource-tfe-sentinel-policy") %>>
                             <a href="/docs/providers/tfe/r/sentinel_policy.html">tfe_sentinel_policy</a>
                         </li>