Add OPA documentation

This documentation covers the general Rego information and also two
specific sections about Open Policy Agent and Gatekeeper.

src/SUMMARY.md

@@ -16,6 +16,16 @@
     - [Write a mutation policy](./writing-policies/rust/05-mutation-policy.md)
     - [Logging](./writing-policies/rust/06-logging.md)
     - [Build and distribute](./writing-policies/rust/07-build-and-distribute.md)
+  - [Rego](./writing-policies/rego/01-intro.md)
+    - [Open Policy Agent](./writing-policies/rego/open-policy-agent/01-intro.md)
+      - [Create a new policy](./writing-policies/rego/open-policy-agent/02-create-policy.md)
+      - [Build and run](./writing-policies/rego/open-policy-agent/03-build-and-run.md)
+      - [Distribute](./writing-policies/rego/open-policy-agent/04-distribute.md)
+    - [Gatekeeper](./writing-policies/rego/gatekeeper/01-intro.md)
+      - [Create a new policy](./writing-policies/rego/gatekeeper/02-create-policy.md)
+      - [Build and run](./writing-policies/rego/gatekeeper/03-build-and-run.md)
+      - [Distribute](./writing-policies/rego/gatekeeper/04-distribute.md)
+    - [Builtin support](./writing-policies/rego/02-builtin-support.md)
   - [Go](./writing-policies/go/01-intro.md)
     - [Create a new policy](./writing-policies/go/02-scaffold.md)
     - [Define policy settings](./writing-policies/go/03-policy-settings.md)

src/writing-policies/rego/01-intro.md

@@ -0,0 +1,82 @@
+# Rego
+
+The Rego language is a tailor made language designed to embrace
+policies as
+code. [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/)
+is a language inspired by Datalog.
+
+There are two ways of writing Rego policies as of today in order to
+implement policies as code in Kubernetes: Open Policy Agent and
+Gatekeeper.
+
+## One language. Two frameworks
+
+### Open Policy Agent
+
+Open Policy Agent is a project that allows you to implement policies
+as code in any project. You can rely on Open Policy Agent for any
+policy based check that you might require in your own application,
+that will in turn execute the required Rego policies.
+
+In this context, writing policies for Kubernetes is just another way
+of exercising Open Policy Agent. By using Kubernetes admission
+webhooks, it's possible to evaluate requests using Open Policy Agent,
+that will in turn execute the policies written in Rego.
+
+Open Policy Agent has some optional integration with Kubernetes
+through its `kube-mgmt` sidecar. When deployed on top of Kubernetes
+and next to the Open Policy Agent server evaluating the Rego policies,
+it is able to replicate the configured Kubernetes resources into Rego
+-- so those Kubernetes resources are visible to all policies. It also
+lets you define policies inside Kubernetes' ConfigMap objects. You can
+read more about it on [its project
+page](https://github.com/open-policy-agent/kube-mgmt).
+
+### Gatekeeper
+
+Gatekeeper is very different from Open Policy Agent in this regard. It
+is focused exclusively to be used in Kubernetes, and takes advantage
+of that as much as it can, making some Kubernetes workflows easier
+than Open Policy Agent in many cases.
+
+## Looking at the differences
+
+Both Open Policy Agent and Gatekeeper policies use Rego to describe
+their policies as code. However, this is only one part of the
+puzzle. Each solution has differences when it comes to writing real
+policies in Rego, and we are going to look at those differences in the
+next sections.
+
+## Entry point
+
+The entry point is the name of a rule within a package, and is the
+rule to be invoked by the runtime when the policy is instantiated.
+
+## Current limitations
+
+### Context-aware policies
+
+Context-aware policies are policies that don't evaluate the input
+request in isolation. They take other factors into account in order to
+take a decision. For example, a policy that evaluates namespaced
+resources and uses an annotation on the parent namespace to configure
+something on the policy. Another example would be a policy that
+evaluates `Ingress` resources, but that in order to take a decision
+has the list of the already existing `Ingress` resources.
+
+The concept of context-aware policies can also extend to custom
+resources, so your policy might want to evaluate a request based on
+currently persisted custom resources as well.
+
+Both Open Policy Agent and Gatekeeper support context-aware
+policies. Right now Kubewarden implements this functionality only for
+policies written with the Kubewarden SDK. We have plans to fill this
+gap, to allow Rego policies to be context-aware policies too.
+
+### Mutating policies
+
+Gatekeeper has support for mutating policies, but Kubewarden has not
+yet implemented mutating policies with Gatekeeper compatibility. You
+can use policies that use the Kubewarden SDK to write mutating
+policies, but at the time of writing, you cannot run Gatekeeper
+mutating policies in Kubewarden yet.

src/writing-policies/rego/02-builtin-support.md

@@ -0,0 +1,36 @@
+# Builtin support
+
+Building a policy for the `wasm` target is only half of the problem,
+it needs to be executed.
+
+The Open Policy Agent team has a dedicated page you can check in order
+to [find out the built-in support
+level](https://www.openpolicyagent.org/docs/latest/policy-reference/#built-in-functions).
+
+When building a Rego policy into a WebAssembly module, some of these
+built-in functions are going to be implemented inside of the Wasm file
+itself (the built-ins marked with a green check in the previously
+linked table) -- regardless of the runtime; while others have to be
+provided at execution time by the WebAssembly runtime evaluating the
+module.
+
+The built-ins marked as `SDK-dependent` are the ones that the host has
+to implement -- in this case, Kubewarden. Open Policy Agent and
+Gatekeeper may use them depending on the needs of the policy. In any
+case, this built-ins are exposed to the policy and any new or existing
+policy could depend on them.
+
+There are still some built-ins that are not yet provided by us,
+however, based on the policies we have seen in the open, the ones we
+already support should be enough for the majority of Kubernetes users.
+
+[This GitHub issue](https://github.com/kubewarden/policy-evaluator/issues/56)
+keeps track of the Rego built-ins we have still to implement. Feel free to
+comment over there to prioritize our work.
+
+## Executing policies with missing built-ins
+
+When a policy is instantiated with `kwctl` or with `policy-server`,
+the list of built-ins used by the policy will be inspected, and if any
+of the used built-ins is missing, the program will abort execution
+logging a fatal error reporting what are the missing built-ins.

src/writing-policies/rego/gatekeeper/01-intro.md

@@ -0,0 +1,19 @@
+# Gatekeeper
+
+Gatekeeper is a project targeting Kubernetes, and as such, has some
+features that are thought out of the box for being integrated with it.
+
+## Compatibility with existing policies
+
+All the existing Gatekeeper policies should be compatible with
+Kubewarden as we will explain during this chapter.
+
+> **Note**: if this is not the case, please report it to us and we
+> will do our best to make sure your policy runs flawlessly with
+> Kubewarden.
+
+Policies have to be compiled with the `opa` CLI to the `wasm` target.
+
+In terms of policy execution, you can read more about the [Open Policy
+Agent built-in support that is implemented in
+Kubewarden](../02-builtin-support.md).

src/writing-policies/rego/gatekeeper/02-create-policy.md

@@ -0,0 +1,99 @@
+# Create a new policy
+
+Let's implement the same policy that [we wrote with Open Policy
+Agent](../open-policy-agent/02-create-policy.md): a policy that
+rejects a resource if it's targeting the `default` namespace.
+
+## Requirements
+
+As in the previous section, we will require the following tools:
+
+- `opa`
+- `kwctl`
+
+## The policy
+
+Gatekeeper policies must return none or more violation objects. If no
+violations are reported, the request will be accepted. If one, or more
+violations are reported, the request will be rejected.
+
+We create a new folder, named `rego-policy`. Inside of it, we create a
+`policy.rego` file with contents:
+
+```rego
+package policy
+
+violation[{"msg": msg}] {
+        input.review.object.metadata.namespace == "default"
+        msg := "it is forbidden to use the default namespace"
+}
+```
+
+In this case, our entrypoint is `policy/violation`, and because of how
+Rego works, the policy can have the following outcomes:
+
+- return 1 violation: the object being reviewed is targeting the
+  default namespace.
+
+- return 0 violations: the object being reviewed is compliant with the
+  policy.
+
+Take a moment to compare this policy with the one we wrote in the Open
+Policy Agent section. That one had to build the whole
+`AdmissionReview` response, and the inputs were slightly
+different. In the Gatekeeper mode, the `AdmissionRequest` object is
+provided at the `input.review` attribute. All attributes of the
+`AdmissionRequest` are readable along with `object`.
+
+Now, let's create the requests that we are going to evaluate in the
+next section.
+
+Let us first create a `default-ns.json` file with the following
+contents inside the `data` directory:
+
+```json
+{
+  "apiVersion": "admission.k8s.io/v1",
+  "kind": "AdmissionReview",
+  "request": {
+    "uid": "1299d386-525b-4032-98ae-1949f69f9cfc",
+    "operation": "CREATE",
+    "object": {
+      "kind": "Pod",
+      "apiVersion": "v1",
+      "metadata": {
+        "name": "nginx",
+        "namespace": "default",
+        "uid": "04dc7a5e-e1f1-4e34-8d65-2c9337a43e64"
+      }
+    }
+  }
+}
+```
+
+Now, let's create another `AdmissionReview` object that this time is
+targeting a namespace different than the `default` one. Let us name
+this file `other-ns.json`. It has the following contents:
+
+```json
+{
+  "apiVersion": "admission.k8s.io/v1",
+  "kind": "AdmissionReview",
+  "request": {
+    "uid": "1299d386-525b-4032-98ae-1949f69f9cfc",
+    "operation": "CREATE",
+    "object": {
+      "kind": "Pod",
+      "apiVersion": "v1",
+      "metadata": {
+        "name": "nginx",
+        "namespace": "other",
+        "uid": "04dc7a5e-e1f1-4e34-8d65-2c9337a43e64"
+      }
+    }
+  }
+}
+```
+
+As you can see, this simulates another pod creation request, this time
+under a namespace called `other`.

src/writing-policies/rego/gatekeeper/03-build-and-run.md

@@ -0,0 +1,83 @@
+# Build and run
+
+Building and running the policy is done exactly the same way as a Rego
+policy targeting Open Policy Agent. The structure of our project is
+like:
+
+```
+.
+├── data
+│   ├── default-ns.json
+│   └── other-ns.json
+└── policy.rego
+
+1 directory, 3 files
+```
+
+## Build
+
+Let's build our policy by running the following `opa` command:
+
+```shell
+$ opa build -t wasm -e policy/violation policy.rego
+```
+
+What this does is build the rego policy, with:
+
+- `target`: `wasm`. We want  to build the policy for the `wasm` target.
+- `entrypoint`: `policy/violation`. The entry point is the `violation`
+rule inside the `policy` package.
+- `policy.rego`: build and include the `policy.rego` file.
+
+The previous command generates a `bundle.tar.gz` file. You can extract
+the wasm module from it:
+
+```shell
+$ tar -xf bundle.tar.gz /policy.wasm
+```
+
+The project tree looks like the following:
+
+```
+.
+├── bundle.tar.gz
+├── data
+│   ├── default-ns.json
+│   └── other-ns.json
+├── policy.rego
+└── policy.wasm
+
+1 directory, 5 files
+```
+
+We can now execute our policy!
+
+## Run
+
+Let's use `kwctl` to run our policy as follows:
+
+```
+$ kwctl run -e gatekeeper --request-path data/other-ns.json policy.wasm | jq
+{
+  "uid": "1299d386-525b-4032-98ae-1949f69f9cfc",
+  "allowed": true
+}
+```
+
+Given that this is our resource created in the namespace called
+`other`, this resource is accepted, as expected.
+
+Now let's execute a request that will be rejected by the policy:
+
+```
+$ kwctl run -e gatekeeper --request-path data/default-ns.json policy.wasm | jq
+{
+  "uid": "1299d386-525b-4032-98ae-1949f69f9cfc",
+  "allowed": false,
+  "status": {
+    "message": "it is forbidden to use the default namespace"
+  }
+}
+```
+
+As you can see, our Gatekeeper policy rejected this resource as expected.