@monokle/validation
v0.33.0
Published
Kubernetes resource validation
Downloads
307
Readme
Welcome to Monokle Validation
Monokle Validation is a TypeScript library to validate your Kubernetes resources.
Key features
- 🚀 Start in seconds with the user-friendly configuration and powerful core plugins.
- ⚡️ Real-time validation through incremental runs.
- ⚒ Extensible architecture with custom plugins.
Core plugins
The validation engine comes with a number of core plugins to provide you with comprehensive validation possibilities for K8s configurations out of the box:
- Pod Security Standards validation for secure deployments
- Kubernetes Schema validation to ensure your resource are compliant with their schemas and a target K8s version
- Resource links validates that reference to other Kubernetes resources are valid.
- Metadata validation for standard and custom labels/annotations
- Common practices validation for basic configuration sanity
- Security policies based on OPA (Open Policy Agent) to reduce your attack surface.
- YAML Syntax validates that your manifests have correct YAML syntax.
Learn more about each Core Plugin in the Core Plugins Documentation
Custom Plugins
Easily create your own validators in typescript - Read More
Community Plugins
Share your custom validators in the Monokle Community Plugins repo, or use any existing community validators as described below.
Validate from the CLI or Monokle Cloud
The Monokle CLI provides a convenient wrapper around this library. Use it to validate your resources in seconds:
kustomize build . | monokle validate -
Or visit Monokle Cloud; a free web application where you can apply this validation library directly on public GitHub repositories.
Table of contents
Getting started
First install the validator with npm:
npm install @monokle/validation
Afterwards you can use it as follows:
const validator = createDefaultMonokleValidator();
await validator.validate({ resources: RESOURCES });
The Monokle validator is extensible and has a rich plugin system. You can configure and preload plugins as follows:
const validator = createDefaultMonokleValidator();
await validator.preload({
plugins: {
"kubernetes-schema": true,
},
});
await validator.validate({ resources });
Configuration
You can customize the rules and settings of the Monokle Validator through an intuitive object.
plugins:
yaml-syntax: true
open-policy-agent: true
kubernetes-schema: true
rules:
yaml-syntax/no-bad-alias: "err"
yaml-syntax/no-bad-directive: false
open-policy-agent/no-last-image: "warn"
settings:
kubernetes-schema:
schemaVersion: v1.24.2
The validation response
The response uses Static Analysis Results Interchange Format (SARIF).
SARIF is a format that provides interoperability between static analysis tools. This means that it decouples the tool that performs the analysis (@monokle/validation, Trivy, Snyk, etc) from the tool that displays the results (Monokle app, Visual Studio Code, GitHub, etc).
SARIF contains both metadata of the tool and the results of the validation. You can learn more about it here.
Example:
{
"$schema": "https://json.schemastore.org/sarif-2.1.0.json",
"version": "2.1.0",
"runs": [
{
"tool": {
"driver": {
"name": "resource-links",
"rules": [
{
"id": "LNK001",
"name": "no-missing-links",
"shortDescription": { "text": "Disallow missing links." },
"fullDescription": {
"text": "The resource has a reference and it cannot be found. This will likely cause problems during deployments."
},
"help": {
"text": "Check whether the referenced resource is missing or has a typo. The reference are often to labels or a names which depends on the property."
}
}
]
}
},
"results": [
{
"ruleId": "LNK001",
"rule": {
"index": 0,
"toolComponent": { "name": "resource-links" }
},
"message": { "text": "Unsatisfied resource link." },
"locations": [
{
"physicalLocation": {
"artifactLocation": {
"uriBaseId": "SRCROOT",
"uri": "kustomize-happy-cms/overlays/local/ingress.yaml"
},
"region": {
"startLine": 17,
"startColumn": 23,
"endLine": 17,
"endColumn": 27
}
}
}
]
}
]
}
]
}
Advanced usage
Preloading
Each validation plugin has to be initialized which might require heavy operations such as fetching large JSON schemas, AJV compilation, WASM initialization and more.
The preload
API avoids a long first validation and is recommended in more interactive environments.
It is idempotent so you can call it as often as you want without continuously reinstantiating the plugins.
Example:
const validator = createDefaultMonokleValidator();
await validator.preload();
await validator.validate({ resources: RESOURCES });
Incremental validation
The incremental
API gives snappy revalidation when editing resources in and want to give feedback in real-time.
Example:
const validator = createDefaultMonokleValidator();
// Initial validation
await validator.validate({
resources: RESOURCES,
});
// Fast revalidation
await validator.validate({
resources: RESOURCES,
incremental: {
resourceIds: ["some-edited-resource-id"],
},
});
// Clear incremental caches.
await validator.clear();
Using Community plugins
The Monokle Validator allows you to add custom plugins from our community repository. All community plugins are thoroughly reviewed and we take care of loading the plugins for you.
Example to load annotations, a community plugin used for demonstrations:
const validator = createExtensibleMonokleValidator();
await validator.preload({
plugins: {
annotations: true,
},
});
await validator.validate({ resources: RESOURCES });
Building user interfaces
The validator exposes plugin or rule metadata and their configuration.
This is great if you'd like to bulid a reactive UI around it.
All metadata will be available after preloading the validator. This way even custom plugins that are downloaded lazily over HTTP have their rules available.
const validator = createExtensibleMonokleValidator();
await validator.preload({
plugins: {
annotations: true,
},
});
const { displayName, description, enabled } = validator.metadata.annotations;
console.log(displayName, description, enabled);
for (const { name, configuration } of validator.rules.annotations) {
console.log(" -", name, configuration.enabled, configuration.level);
}
await validator.validate({ resources: RESOURCES });
Caveats
- Use
processRefs
before validating with a resource-links validator. It creates a graph between resources and sees if links between them are present or missing. - @monokle/validation expects fetch on global scope so please use isomorphic-fetch if this is not available (e.g. NodeJs).