Skip to content

Commit

Permalink
Merge pull request #360 from jhkrug/polspec-45
Browse files Browse the repository at this point in the history 
Review and update policy specification 4 & 5
  • Loading branch information
@jhkrug
jhkrug authored Feb 20, 2024
2 parents c38a3b2 + 9c2308c commit 109fa78
Show file tree
Hide file tree
Showing 2 changed files with 46 additions and 35 deletions.
31 changes: 15 additions & 16 deletions docs/reference/spec/04-mutating-policies.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,20 @@ title: Mutating policies
description: Mutating policies.
keywords: [kubewarden, kubernetes, policy specification, mutating policies]
doc-persona: [kubewarden-policy-developer]
doc-type: [treference]
doc-type: [reference]
doc-topic: [writing-policies, specification, mutating-policies]
---

<head>
<link rel="canonical" href="https://docs.kubewarden.io/reference/spec/mutating-policies"/>
</head>

Mutating policies are structured in the very same way as validating ones:
* They have to register `validate` and `validate_settings` waPC functions
* The communication API used between the host and the policy is the very same
as the one used by validating policies.
Mutating policies are structured in the same way as validating ones:

Mutating policies can accept a request and propose a mutation of the incoming
- They have to register `validate` and `validate_settings` waPC functions.
- The communication API used between the host and the policy is the same as that used by validating policies.

Mutating policies accept a request and can propose a mutation of the incoming
object by returning a `ValidationResponse` object that looks like this:

```json
Expand All @@ -27,8 +27,8 @@ object by returning a `ValidationResponse` object that looks like this:
}
```

The `mutated_object` field contains the object the policy wants to be created
inside of the Kubernetes cluster serialized to JSON.
The `mutated_object` field contains the object the policy wants to be created in the Kubernetes cluster,
serialized to JSON.

## A concrete example

Expand Down Expand Up @@ -64,7 +64,7 @@ Let's assume the policy received this `ValidationRequest`:
```

:::note
We left some irrelevant fields out of the `request` object.
For learning purposes we left some unimportant fields out of the `request` object.
:::

This request is generated because someone tried to create a Pod that would
Expand Down Expand Up @@ -141,16 +141,15 @@ spec:
- BPF
```

As you can see, the policy altered the `securityContext.capabilities.drop`
section of the only container declared inside of the Pod.
As you can see, the policy altered the `securityContext.capabilities.drop` section of the only container declared in the Pod.

The container is now dropping the `BPF` capability thanks to our policy.
The container is now dropping the `BPF` capability due to our policy.

## Recap

These are the functions a mutating policy must implement:

| **waPC function name** | **Input payload** | **Output payload** |
|------------------------|---------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `validate` | <code>\{<br/> "request": \{<br/> // AdmissionReview.request data<br/> \},<br/> "settings": \{<br/> // your policy configuration<br/> \}<br/>\}</code> | <code>\{<br/> **// mandatory**<br/> "accepted": boolean,<br/><br/> // optional, ignored if accepted<br/> // recommended for rejections<br/> "message": string,<br/><br/> // optional, ignored if accepted<br/> "code": integer, <br/><br/> // JSON Object to be created<br/> // Can be used only when the<br/> // request is accepted<br/> "mutated_object": object<br/>\}</code> |
| `validate_settings` | <code>\{<br/><br/> // your policy configuration<br/><br/>\}</code> | <code>\{<br/> **// mandatory**<br/> "validate": boolean,<br/><br/> // optional, ignored if accepted<br/> // recommended for rejections<br/> "message": string,<br/>\}</code> |
| **waPC function name** | **Input payload** | **Output payload** |
|-|-|-|
| `validate` | <code>\{<br/> "request": \{<br/> // AdmissionReview.request data<br/> \},<br/> "settings": \{<br/> // your policy configuration<br/> \}<br/>\}</code> | <code>\{<br/> **// mandatory**<br/> "accepted": boolean,<br/><br/> // optional, ignored if accepted<br/> // recommended for rejections<br/> "message": string,<br/><br/> // optional, ignored if accepted<br/> "code": integer, <br/><br/> // JSON Object to be created<br/> // Can be used only when the<br/> // request is accepted<br/> "mutated_object": object<br/>\}</code> |
| `validate_settings` | <code>\{<br/><br/> // your policy configuration<br/><br/>\}</code> | <code>\{<br/> **// mandatory**<br/> "validate": boolean,<br/><br/> // optional, ignored if accepted<br/> // recommended for rejections<br/> "message": string,<br/>\}</code> |
50 changes: 31 additions & 19 deletions docs/reference/spec/05-context-aware-policies.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,10 @@ doc-topic: [writing-policies, specification, context-aware-policies]
<link rel="canonical" href="https://docs.kubewarden.io/reference/spec/context-aware-policies"/>
</head>

The `policy-server` has capabilities to expose cluster information to
policies, so that they can take decisions based on other existing
resources, and not only based on the details provided by the admission request.
The `policy-server` has the capability to expose cluster information to
policies,
so that they can take decisions based on other existing resources,
and not only based on the details provided by the admission request.

The retrieval of Kubernetes resources is performed by the Policy Server hosting the policy.
Access to Kubernetes is regulated by RBAC rules applied to the Service Account used by the Policy Server.
Expand All @@ -25,13 +26,18 @@ The `default` Policy Server deployed by Kubewarden helm charts has access to the
- Services
- Ingresses

## Support Matrix
:::caution
The policy server performs caching of the results obtained from the Kubernetes API server to reduce the amount of load on this core part of Kubernetes.
That means some information might be stale or missing.
:::

## Support matrix

| Policy type | Support | Notes |
| --------------------------------- | :-----: | ------------------------------------------------ |
| Traditional programming languages | ✅ | - |
| Rego | ✅ | Since Kubewarden 1.9 release |
| WASI | ✅ | Since Kubewarden 1.10.0 release, only for Go SDK |
| Policy type | Support | Notes |
|-|:-:|-|
| Traditional programming languages | ✅ | - |
| Rego | ✅ | Since Kubewarden 1.9 release |
| WASI | ✅ | Since Kubewarden 1.10.0 release, only for Go SDK |

## Constraints

Expand Down Expand Up @@ -82,13 +88,18 @@ The direct/cached query behavior can be configured on a per-query level by the p

## ClusterAdmissionPolicies

ClusterAdmissionPolicies have the field [spec.contextAwareResources](https://doc.crds.dev/github.com/kubewarden/kubewarden-controller/policies.kubewarden.io/ClusterAdmissionPolicy/v1#spec-contextAwareResources). This field provides a list a `GroupVersionKind` resources that the policy needs to access. This allows policy writers to ship the "permissions" that the policy needs together with the policy. Moreover, this allows policy operators to review the "permissions" needed by the policy at deployment time.
ClusterAdmissionPolicies have the field
[spec.contextAwareResources](https://doc.crds.dev/github.com/kubewarden/kubewarden-controller/policies.kubewarden.io/ClusterAdmissionPolicy/v1#spec-contextAwareResources).
This field provides a list a `GroupVersionKind` resources that the policy needs to access.
This allows policy writers to ship the "permissions" that the policy needs together with the policy.
Moreover, this allows policy operators to review the "permissions" needed by the policy at deployment time.

### Testing context aware policies locally

Apart from running policies in cluster for end-to-end tests, one can use our `kwctl` CLI utility to run policies and mock requests against the cluster.
As well as running policies in a cluster for end-to-end tests,
you can use the `kwctl` CLI utility to run policies and mock requests against the cluster.

For that, `kwctl run` can first record all the interactions with the cluster into a file:
For this, `kwctl run` can first record all the interactions with the cluster into a file:

```console
kwctl run \
Expand Down Expand Up @@ -116,8 +127,9 @@ which creates the following `replay-session.yml` file:
payload: '{"apiVersion":"","kind":"Pod", <snipped> }'
```
With the replay session, one can now mock the cluster interactions without the need
of a cluster, perfect for CI and end-to-end tests:
With the replay session,
you can now simulate the cluster interactions without the need of a cluster,
which is ideal for CI and end-to-end tests:
```console
kwctl run \
Expand All @@ -129,9 +141,7 @@ kwctl run \

## Language SDKs

Language SDK's that support cluster context at this time will expose
functions that allow policies to retrieve the current state of the
cluster.
Language SDK's that support cluster context at the moment expose functions that allow policies to retrieve the current state of the cluster.

:::tip
If you want more information about the waPC function used by the SDKs, check the [Kubernetes capabilities](host-capabilities/06-kubernetes.md) reference documentation.
Expand All @@ -155,7 +165,9 @@ The inventory is populated with the resources the policy has been granted access

### Open Policy Agent

The context aware information is exposed under the `data.kubernetes` key, like
[`kube-mgmt`](https://github.com/open-policy-agent/kube-mgmt) does by default.
The context aware information is exposed under the `data.kubernetes` key,
like
[`kube-mgmt`](https://github.com/open-policy-agent/kube-mgmt)
does by default.

The inventory is populated with the resources the policy has been granted access to via the `spec.contextAwareResources` field.

0 comments on commit 109fa78

Please sign in to comment.