https://github.com/pfnet/kaptest
https://github.com/pfnet/kaptest
Last synced: about 1 year ago
JSON representation
- Host: GitHub
- URL: https://github.com/pfnet/kaptest
- Owner: pfnet
- License: apache-2.0
- Created: 2024-08-27T01:42:10.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-02-18T10:39:24.000Z (over 1 year ago)
- Last Synced: 2025-05-05T04:42:10.271Z (about 1 year ago)
- Language: Go
- Size: 185 KB
- Stars: 10
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Kaptest
**Kubernetes Admission Policy TESTing tool**
Kaptest is a testing tool to check the CEL expressions of [Validating Admission Policy](https://kubernetes.io/docs/reference/access-authn-authz/validating-admission-policy/).
Kaptest specializes in evaluating CEL expressions.
It allows you to perform fast and simple testing of CEL expressions,
without having to start the kube-apiserver, create the `ValidatingAdmissionPolicy` and parameter resources, or link it to the target resources using `ValidatingAdmissionPolicyBinding`.
## Installation
You can install Kaptest by downloading the compiled binary from the [release page](https://github.com/pfnet/kaptest/releases). It can also be installed by using the following script:
```shell
curl -sLO "https://github.com/pfnet/kaptest/releases/download/${KAPTEST_VERSION}/kaptest_${KAPTEST_VERSION}_${OS}_${ARCH}.tar.gz"
tar -xvf "kaptest_${KAPTEST_VERSION}_${OS}_${ARCH}.tar.gz"
```
## How to Use
### Setup Test Manifests
If you want to create a test for `./validatingadmissionpolicy.yaml`, run the following command:
```shell
kaptest init validatingadmissionpolicy.yaml
```
This will create a `./validatingadmissionpolicy.test` directory and generate a skeleton for writing test cases.
```shell
$ tree validationgadmissionpolicy.test/
validationgadmissionpolicy.test/
├── kaptest.yaml
└── resources.yaml
$ cat validationgadmissionpolicy.test/kaptest.yaml
validatingAdmissionPolicies:
- ../validationgadmissionpolicy.yaml
resources:
- resources.yaml
testSuites:
- policy: simple-policy
tests:
- object:
kind: CHANGEME
name: ok
expect: admit
- object:
kind: CHANGEME
name: bad
expect: deny
```
### Test File Structures
There are no restrictions on the test file names. Although the skeleton created by `kaptest init` uses `kaptest.yaml`, other names can also be used.
Test files should be written in the following format:
```yaml
validatingAdmissionPolicies:
-
-
resources:
-
-
testSuites:
- policy: # ValidatingAdmissionPolicy's name
tests:
- object:
group: # Optional
version: # Optional
kind: # Required
namespace: # Optional: It is needed to match with a resource whose namespace is set.
name: # Required
oldObject:
group: # Optional
version: # Optional
kind: # Required
namespace: # Optional
name: # Required
params: # GVK of Params is omitted since it is defined by `spec.ParamKind` field in ValidatingAdmissionPolicy
namespace: # Optional
name: # Required
userInfo: # The same struct as request.userInfo
user:
groups:
extra: ...
expect:
```
Resources specified in the `object`, `oldObject`, `params`, and `namespace` fields of the test cases must be described in the YAML files specified in the `resources` field.
### Run test
The tests defined in the above manifest can be run with the following command:
```shell
kaptest run ...
```
You can run test cases of multiple YAML files at once and display the test results together.
### Operation Type
You can describe the cases for CREATE, UPDATE, and DELETE operations based on whether object and oldObject are specified. These are determined by the following conditions:
- **CREATE**: Specify only object
- **UPDATE**: Specify both object and oldObject
- **DELETE**: Specify only oldObject
### Evaluation Results
Kaptest focuses on evaluating CEL expressions, so even when an error occurs or `matchConditions` are not met it does not change the result to `allow` or `deny`. The test results of Kaptest will be one of the following four values:
- **allow**: When all `matchConditions` and `validations` are evaluated as `true`
- **deny**: When all `matchConditions` are evaluated as `true`, and at least one `validation` is evaluated as `false`
- **skip**: When at least one `matchCondition` is evaluated as `false`
- **error**: When at least one `matchCondition` or `validation` cannot be evaluated
Even if you configure the `spec.failurePolicy`, it will not affect the test results.
## Examples
Examples are [here](./examples/).
## Caveats
- Note that `matchExpressions` are never evaluated in this tool. This means you can specify any objects or oldObjects that do not satisfy `matchExpressions` in your test cases, though this is not recommended as it does not constitute a valid test case.
- The following [CEL variables](https://kubernetes.io/docs/reference/access-authn-authz/validating-admission-policy/#validation-expression) are not supported for now.
- `request.requestResource`
- `request.subResource`
- `request.requestSubResource`
- `request.options`
- `authorizer`
- The following attributes are fixed and cannot be changed.
- `request.dryRun` = `True`
- Since Kaptest is a testing tool, dryRun is always set to true.
## License
Copyright (c) 2024 Preferred Networks. All rights reserved. See [LICENSE](./LICENSE) for details.