docs/deployments: add capabilities section (open-policy-agent#3839)

Adding in instructions to the OPA docs on how to use capabilities feature.

Fixes: open-policy-agent#3769

Signed-off-by: Peter ONeill <peteroneilljr@gmail.com>
Signed-off-by: Dolev Farhi <farhi.dolev@gmail.com>

docs/content/deployments.md

@@ -346,6 +346,7 @@ $ curl localhost:8181/v1/data/baz
 Just because OPA has returned an answer for a policy query, that does not indicate that it was operationally ready for that query.  Moreover, the operational readiness of OPA cannot be ascertained from the query response, as illustrated above.  Two issues must therefore be addressed: how to know when OPA is operationally ready for policy queries and how to make a decision before OPA is ready.
 
 ### Ensuring Operational Readiness
+
 The relevance of the discussion above depends on how you have chosen to deploy policies into OPA.
 
 If you deploy policies to OPA on disk (e.g. volume mounting into the OPA container on Kubernetes), then OPA will only start answering policy queries once all the policies are successfully loaded.  In this case, it is impossible for OPA to answer policy queries before it has loaded policy, so the discussion above is a non-issue.
@@ -364,3 +365,119 @@ The mechanisms discussed above ensure that OPA is not asked to answer policy que
 The choices are more varied if the policy is not making an allow/deny decision, but often there is some analog to fail-open and fail-closed.  The key observation is that this logic is entirely the responsibility of the software asking OPA for a policy decision.  Despite the fact that what to do when OPA is unavailable is technically a policy question, it is one that we cannot rely on OPA to answer.  The right logic can depend on many factors including the likelihood of OPA not making a decision and the cost of allowing or denying a request incorrectly.
 
 In Kubernetes admission control, for example, the Kubernetes admin can choose whether to fail-open or fail-closed, leaving the decision up to the user.  And often this is the correct way to build an integration because it is unlikely that there is a universal solution.  For example, running an OPA-integration in a development environment might require fail-open, but running exactly the same integration in a production environment might require fail-closed.
+
+## Capabilities
+
+OPA now supports a _capabilities_ check on policies. The check allows callers to restrict the [built-in](../policy-reference/#built-in-functions) functions that policies may depend on. If the policies passed to OPA require built-ins not listed in the capabilities structure, an error is returned. The capabilities check is currently supported by the `check` and `build` sub-commands and can be accessed programmatically on the `ast.Compiler` structure. The OPA repository includes a set of capabilities files for previous versions of OPA in the [capabilities](https://github.com/open-policy-agent/opa/tree/main/capabilities) folder.
+
+For example, given the following policy:
+
+```rego
+package example
+
+deny["missing semantic version"] {
+  not valid_semantic_version_tag
+}
+
+valid_semantic_version_tag {
+  semver.is_valid(input.version)
+}
+```
+
+We can check whether it is compatible with different versions of OPA:
+
+```bash
+# OK!
+$ opa build ./policies/example.rego --capabilities ./capabilities/v0.22.0.json
+
+# ERROR!
+$ opa build ./policies/example.rego --capabilities ./capabilities/v0.21.1.json
+```
+
+### Built-ins
+
+The 'build' command can validate policies against a configurable set of OPA capabilities. The capabilities define the built-in functions and other language features that policies may depend on. For example, the following capabilities file only permits the policy to depend on the "plus" built-in function ('+'):
+
+```json
+{
+    "builtins": [
+        {
+            "name": "plus",
+            "infix": "+",
+            "decl": {
+                "type": "function",
+                "args": [
+                    {
+                        "type": "number"
+                    },
+                    {
+                        "type": "number"
+                    }
+                ],
+                "result": {
+                    "type": "number"
+                }
+            }
+        }
+    ]
+}
+```
+
+The following command builds a directory of policies ('./policies') and validates them against `capability-built-in-plus.json`:
+
+```bash
+opa build ./policies --capabilities ./capability-built-in-plus.json
+```
+
+### Network
+
+When passing a capabilities definition file via `--capabilities`, one can restrict which hosts remote schema definitions can be retrieved from. For example, a `capabilities.json` containing the json below would disallow fetching remote schemas from any host but "kubernetesjsonschema.dev". Setting `allow_net` to an empty array would prohibit fetching any remote schemas.
+
+**capabilities.json**
+```json
+{
+    "builtins": [ ... ],
+    "allow_net": [ "kubernetesjsonschema.dev" ]
+}
+```
+
+Not providing a capabilities file, or providing a file without an `allow_net` key, will permit fetching remote schemas from any host.
+
+Note that the metaschemas http://json-schema.org/draft-04/schema, http://json-schema.org/draft-06/schema, and http://json-schema.org/draft-07/schema, are always available, even without network access.
+
+### Building your own capabilities JSON
+
+Use the following JSON structure to build more complex capability checks. 
+
+```json
+{
+    "builtins": [
+        {
+            "name": "name", // REQUIRED: Unique name of built-in function, e.g., <name>(arg1,arg2,...,argN)
+
+            "infix": "+",  // OPTIONAL: Unique name of infix operator. Default should be unset.
+
+            "decl": {  // REQUIRED: Built-in function type declaration.
+
+                "type": "function", // REQUIRED: states this is a function 
+
+                "args": [ // REQUIRED: List of types to be passed in as an arguement: any, number, string, boolean, object, array, set. 
+                    {
+                        "type": "number" 
+                    },
+                    {
+                        "type": "number"
+                    }
+                ],
+                "result": { // REQUIRED: The expected result type.
+                    "type": "number"
+                }
+            }
+        }
+    ],
+    "allow_net": [ // OPTIONAL: allow_net is an array of hostnames or IP addresses, that an OPA instance is allowed to connect to.
+      "mycompany.com",
+      "database.safe",
+    ]
+}
+```