https://github.com/kubewarden/cel-policy
A policy that can run CEL expressions
https://github.com/kubewarden/cel-policy
common-expression-language kubernetes kubernetes-security kubewarden-policy policy-as-code webassembly
Last synced: 10 months ago
JSON representation
A policy that can run CEL expressions
- Host: GitHub
- URL: https://github.com/kubewarden/cel-policy
- Owner: kubewarden
- License: apache-2.0
- Created: 2024-01-31T11:13:23.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-12-09T10:37:28.000Z (over 1 year ago)
- Last Synced: 2024-12-09T11:36:20.543Z (over 1 year ago)
- Topics: common-expression-language, kubernetes, kubernetes-security, kubewarden-policy, policy-as-code, webassembly
- Language: Go
- Homepage:
- Size: 334 KB
- Stars: 5
- Watchers: 8
- Forks: 5
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
[](https://github.com/kubewarden/community/blob/main/REPOSITORIES.md#policy-scope)
[](https://github.com/kubewarden/community/blob/main/REPOSITORIES.md#stable)
## CEL Policy
This policy is a meta-policy that allows to run [CEL](https://github.com/google/cel-go) expressions
against Kubernetes resources.
A meta-policy is a policy that can be configured via settings, and does not require to be recompiled to change its behavior, acting as a DSL.
The settings of the policy are compliant with the [ValidatingAdmissionPolicy Kubernetes resource](https://kubernetes.io/docs/reference/access-authn-authz/validating-admission-policy/),
please refer to [writing a policy](#writing-a-policy) for more information on what fields are supported.
Under the hood, the policy uses [CEL](https://github.com/google/cel-go) and [Kubernetes CEL libraries](https://pkg.go.dev/k8s.io/apiserver/pkg/cel/library),
this allows to use the same CEL syntax and functions that are available in Kubernetes.
### Writing a policy
Both `validations` and `variables` fields are supported.
The policy provides the following variables:
- `request`: the admission request
- `object`: the Kubernetes resource being validated
- `oldObject`: the Kubernetes resource before the update, nil if the request is not an update
- `namespaceObject`: the namespace of the resource being validated
The policy will be evaluated as `allowed` if all the CEL expressions are evaluated as `true`.
It is required that the validations expression is a boolean, otherwise the policy will not pass the settings validation phase.
A `message` or a `messageExpression` can be specified to provide a custom message when the policy is evaluated as `false`.
The `messageExpression` will be evaluated as a CEL expression, and the result will be used as the message.
It is required that the message expression is a string, otherwise the policy will not pass the settings validation phase.
For more information about variables and validation expressions, please refer to the [ValidatingAdmissionPolicy Kubernetes resource](https://kubernetes.io/docs/reference/access-authn-authz/validating-admission-policy/).
### Example
Given the following `ValidatingAdmissionPolicy`:
```yaml
apiVersion: admissionregistration.k8s.io/v1beta1
kind: ValidatingAdmissionPolicy
metadata:
name: "demo-policy.example.com"
spec:
failurePolicy: Fail
matchConstraints:
resourceRules:
- apiGroups: ["apps"]
apiVersions: ["v1"]
operations: ["CREATE", "UPDATE"]
resources: ["deployments"]
variables:
- name: replicas
expression: "object.spec.replicas"
validations:
- expression: "variables.replicas <= 5"
message: "The number of replicas must be less than or equal to 5"
```
the Kubewarden CEL policy can be written as follows:
```yaml
apiVersion: policies.kubewarden.io/v1
kind: AdmissionPolicy
metadata:
annotations:
io.kubewarden.policy.category: Resource validation
io.kubewarden.policy.severity: low
name: "demo-policy.example.com"
spec:
module: registry://ghcr.io/kubewarden/policies/cel-policy:latest
settings:
variables:
- name: "replicas"
expression: "object.spec.replicas"
validations:
- expression: "variables.replicas <= 5"
message: "The number of replicas must be less than or equal to 5"
rules:
- apiGroups: ["apps"]
apiVersions: ["v1"]
operations: ["CREATE", "UPDATE"]
resources: ["deployments"]
mutating: false
backgroundAudit: false
```
## Host capabilities
Kubewarden's [host capabilities](https://docs.kubewarden.io/reference/spec/host-capabilities/intro-host-capabilities) can be accessed by CEL extension libraries available in the policy environment.
The following host capabilities are available:
| Capability | Description | Documentation |
| --------------------------------------------------------------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| [kubernetes](https://docs.kubewarden.io/reference/spec/host-capabilities/kubernetes) | Access to Kubernetes resources in the cluster | [**Kubernetes**](https://pkg.go.dev/github.com/kubewarden/cel-policy/internal/cel/library#Kubernetes) |
| [sigstore](https://docs.kubewarden.io/reference/spec/host-capabilities/signature-verifier-policies) | Sigstore (secure supply chain) support | [**Sigstore**](https://pkg.go.dev/github.com/kubewarden/cel-policy/internal/cel/library#Sigstore) |
| [oci](https://docs.kubewarden.io/reference/spec/host-capabilities/container-registry) | Interact with container registries | [**OCI**](https://pkg.go.dev/github.com/kubewarden/cel-policy/internal/cel/library#OCI) |
| [crypto](https://docs.kubewarden.io/reference/spec/host-capabilities/crypto) | Host-side cryptographic functions | [**Crypto**](https://pkg.go.dev/github.com/kubewarden/cel-policy/internal/cel/library#Crypto) |
| [net](https://docs.kubewarden.io/reference/spec/host-capabilities/net) | Network operations | [**Net**](https://pkg.go.dev/github.com/kubewarden/cel-policy/internal/cel/library#Net) |
## Extensions
CEL policy has some extensions that add extra functionality to the language that are not defined in the language definition. The CEL policy has the following extensions enabled:
| Extension | Description | Documentation |
| --------------- | -------------------------------------------- | ----------------------------------------------------------------------------- |
| Base64 Encoders | Allows users to encode/decode base64 strings | [Encoder extension](https://pkg.go.dev/github.com/google/cel-go/ext#Encoders) |
## Known limitations
At the moment the policy does not support the following Kubernetes extensions:
- [authz](https://pkg.go.dev/k8s.io/apiserver/pkg/cel/library#Authz)