Skip to content

Commit

Permalink
Add OPA documentation
Browse files Browse the repository at this point in the history 
This documentation covers the general Rego information and also two
specific sections about Open Policy Agent and Gatekeeper.
  • Loading branch information
@ereslibre
ereslibre committed Aug 27, 2021
1 parent b957f8d commit acd39ca
Show file tree
Hide file tree
Showing 11 changed files with 838 additions and 0 deletions.
10 changes: 10 additions & 0 deletions src/SUMMARY.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
47 changes: 47 additions & 0 deletions src/writing-policies/rego/01-intro.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# Rego

The Rego language is a tailor made language designed to embrace
policies as code. Rego 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 leverage Kubernetes' admission webhooks 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 aalso
lets you define policies inside Kubernetes' configmaps. 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.
102 changes: 102 additions & 0 deletions src/writing-policies/rego/02-builtin-support.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
# 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).

Every green check in this table means that those built-ins are
implemented regardless of the runtime: they are built on top of other
functions and are implemented already on the policy you have built.

The built-ins marked as `SDK-dependent` are the ones that the host has
to implement -- in this case, Kubewarden. Open Policy Agent may use
them in order to build the rest of the built-ins. In any case, this
built-ins are exposed to the policy and any new or existing policy
could depend on them.

This is the built-ins implemented up until now in Kubewarden:


| Category | Built-in | Status |
|--------------------|---------------------------------------------|-------------|
| Numbers | `rand.intn` | - |
| <br/> | | |
| Objects | `json.patch` | - |
| <br/> | | |
| Strings | `sprintf` | Implemented |
| <br/> | | |
| Regex | `regex.split` | - |
| | `regex.globs_match` | - |
| | `regex.template_match` | - |
| | `regex.find_n` | - |
| <br/> | | |
| Glob | `glob.quote_meta` | - |
| <br/> | | |
| Units | `units.parse_bytes` | - |
| <br/> | | |
| Encoding | `base64url.encode_no_pad` | - |
| | `urlquery.encode` | - |
| | `urlquery.encode_object` | - |
| | `urlquery.decode` | - |
| | `urlquery.decode_object` | - |
| | `json.is_valid` | - |
| | `yaml.marshal` | - |
| | `yaml.unmarshal` | - |
| | `yaml.is_valid` | - |
| | `hex.encode` | - |
| | `hex.decode` | - |
| <br/> | | |
| Token Signing | `io.jwt.encode_sign_raw` | - |
| | `io.jwt.encode_sign` | - |
| <br/> | | |
| Token Verification | `io.jwt.verify_rs256` | - |
| | `io.jwt.verify_rs384` | - |
| | `io.jwt.verify_rs512` | - |
| | `io.jwt.verify_ps256` | - |
| | `io.jwt.verify_ps384` | - |
| | `io.jwt.verify_ps512` | - |
| | `io.jwt.verify_es256` | - |
| | `io.jwt.verify_es384` | - |
| | `io.jwt.verify_es512` | - |
| | `io.jwt.verify_hs256` | - |
| | `io.jwt.verify_hs384` | - |
| | `io.jwt.verify_hs512` | - |
| | `io.jwt.decode` | - |
| | `io.jwt.decode_verify` | - |
| <br/> | | |
| Time | `time.now_ns` | - |
| | `time.parse_ns` | - |
| | `time.parse_rfc3339_ns` | - |
| | `time.parse_duration_ns` | - |
| | `time.date` | - |
| | `time.clock` | - |
| | `time.weekday` | - |
| | `time.add_date` | - |
| | `time.diff` | - |
| <br/> | | |
| Cryptography | `crypto.x509.parse_certificates` | - |
| | `crypto.x509.parse_and_verify_certificates` | - |
| | `crypto.x509.parse_certificate_request` | - |
| | `crypto.md5` | - |
| | `crypto.sha1` | - |
| | `crypto.sha256` | - |
| <br/> | | |
| HTTP | `http.send` | - |
| <br/> | | |
| Net | `net.cidr_contains_matches` | - |
| | `net.cidr_expand` | - |
| | `net.cidr_merge` | - |
| <br/> | | |
| UUID | `uuid.rfc4122` | - |
| <br/> | | |
| Semantic Versions | `semver.is_valid` | - |
| | `semver.compare` | - |
| <br/> | | |
| Rego | `rego.parse_module` | - |
| <br/> | | |
| OPA | `opa.runtime` | - |
| <br/> | | |
| Debugging | `trace` | - |
19 changes: 19 additions & 0 deletions src/writing-policies/rego/gatekeeper/01-intro.md
View file
Original file line number Diff line number Diff line change
@@ -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 Gatekeeper policies that you have written already 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 in
> Kubewarden.
They have to be recompiled 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).
48 changes: 48 additions & 0 deletions src/writing-policies/rego/gatekeeper/02-create-policy.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# 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

Since Gatekeeper is targeting Kubernetes, it has the freedom to be
more handy in what the policy has to return.

With Open Policy Agent we had to construct a whole `AdmissionReview`
object as the response of our policy. With Gatekeeper, we only have to
return none or more violations from our policy entrypoint.

If none violations were reported, the request will be accepted. If
one, or more violations were 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, it can either have 1 violation: if the object to be
reviewed is targeting the `default` namespace, or 0 violations
otherwise.

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`.
82 changes: 82 additions & 0 deletions src/writing-policies/rego/gatekeeper/03-build-and-run.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# Build and run

Building and running the policy is done exactly the same as a Rego
policy targeting Open Policy Agent. The structure 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
~/gatekeeper-policy » 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/main`. The entry point is the `main` rule
inside the `policy` package.
- `policy.rego`: build and include the `policy.rego` file.
- `request.rego`: build and include the `request.rego` file.

After the build is complete, `opa build` will have generated a
`bundle.tar.gz` file. You can extract it:

```shell
gatekeeper-policy » tar -xf bundle.tar.gz /policy.wasm
```

The tree looks like:

```
.
├── 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:

```
gatekeeper-policy » 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:

```
gatekeeper-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.
Loading

0 comments on commit acd39ca

Please sign in to comment.