Monokle blog

Monokle-CLI: Flexible Kubernetes YAML Validation

Dec 8, 2022
7 min
read
Tackle your Kubernetes pre-deployment tasks and achieve quality deployments with the only YAML validator you’ll even need – Monokle CLI.
Ole Lensmar
CTO
monokle

Table of Contents

Monokle-CLI: Flexible Kubernetes YAML Validation

The importance of validation of your Kubernetes YAMLs as part of your pre-commit/deploy workflows is evident as the adoption of GitOps-based workflows grows. Performing validations later in your workflows - as part of your PR process or even in-cluster as validation Webhooks is a valuable practice, but should perhaps be seen more as a safety net than as the primary method to enforce the quality of your YAMLs. Validating early in your development workflows decreases turnaround times from hours/minutes to seconds - instead of having to wait for your PR-bot or GitOps reconciler to tell you things don’t seem right - your local tooling tells you before you commit or deploy anything.

A fancy way of describing this focus on pre-deployment quality is “shift-left” - and a variety of tools for pre-commit/deploy validation are available - unfortunately none of them provide the flexibility and power on their own that platform engineers need to provide guard-rails for their development teams to deliver high-quality deployments in line with corporate or team guidelines - and a lot of time ends up being spent on building custom solutions and/or resorting to post-deployment quality enforcement.

## What is monokle-cli?

In our ongoing efforts to provide K8s engineers with a consistent toolchain to achieve pre-deployment quality, we have extracted the core validation logic from our popular Monokle Desktop tool - beefed it up with powerful configuration and extension mechanisms - and packaged it in a CLI and GitHub action to provide you with a one-stop solution to validate your Kubernetes YAMLs, consistently across teams and workflows, before you commit or deploy them to your cluster(s).

To that end, Monokle CLI can be leveraged out-of-the-box to validate: 

* YAML syntax

* The schemas of your YAMLs against a configurable K8s version

* Links/references between Kubernetes resources

* A set of predefined OpenPolicyAgent (OPA) policies

* Custom rules written in typescript

Monokle automatically configures all of the validators listed above through an es-lint inspired configuration approach. This configuration is honored by the Monokle CLI as well as the corresponding GitHub Action and will soon carry over to other tools in our ecosystem including Monokle Cloud and Monokle Desktop.

As with other tools in the Monokle ecosystem, Monokle-CLI is 100% open-source - MIT licensed.

## Jumping in…

Enough talk - let’s jump straight in. Install the monokle-cli with (you’ll need npm installed for now)

`npm install --global @monokle/cli`

Switch to a folder containing Kubernetes manifests and run the validator

`monokle validate <file/folder containing manifests>`

We’ll use the standalone deployment example from the [monokle-demo repo](https://github.com/kubeshop/monokle-demo) going forward:

yaml deployment templates

As you can see, we immediately found a bunch of errors - let’s create a `monokle.validation.yaml` config file to disable these OPA-related errors since they don’t really apply to us, and add the correct k8s schema version for the schema validation:

Run the command again.

CLI tooling

Much better! All validator plugins and their settings and rules are [documented on GitHub](https://github.com/kubeshop/monokle-core/blob/main/packages/validation/docs/configuration.md).

## Integrating with CI / CD

Ensuring that your configured rules are honored before you merge your changes is a good safety net to catch rogue commits and YAML delinquents! Monokle-cli can of course easily be configured to run as part of your pipelines. If  you’re on GitHub, the [monokle-github-action](https://github.com/marketplace/actions/monokle-validation) is a convenient way to ensure validation as part of your PR validations.

(Don’t forget  to commit the configuration file to your repo so the GitHub action can use it...) 

See more examples at [https://github.com/marketplace/actions/monokle-validation#usage](https://github.com/marketplace/actions/monokle-validation#usage)

Once executed, GitHub will show the outcome in the PR:

Devops test run in github

Going to the details of a failed check will show

Details and errors for deployment

## Creating and Sharing Custom Validators

One of the more powerful aspects of the Monokle-cli is the possibility to easily create, debug and share custom validators using typescript as the programming language. The process for this is straightforward:

1. Bootstrap your own validator using the provided scaffolding in our [community-plugins repository](https://github.com/kubeshop/monokle-community-plugins)

2. Implement the validator in typescript, optionally using automatically generated types for target K8s resource kinds 

3. Debug your validator in real-time using Monokle Cloud (optional - see below)

4. Publish the validator to the community plugin repository (if you want to share)

5. Use it using the configuration approach described above (Monokle CLI automatically uses all plugins in the community repository)

We won’t go into the details here but we will cover this in a separate blog-post very soon.

Just to give you a taste of how easy it is to create a custom validator, here is a very simple example that ensures that each resource has at least one annotation:

(This is taken from the corresponding [community plugin on GitHub](https://github.com/kubeshop/monokle-community-plugins/blob/main/validation/annotations/src/rules/noEmptyAnnotations.ts))

Violating this rule results in:

cli error reading

And here you can see it in action in the Monokle Cloud UI (more on that below…)

cloud based deployment to github

## Integrating with Monokle Cloud

[Monokle Cloud](https://app.monokle.com/) is a free browser-based tool for exploring, previewing and validating Kubernetes resources in public GitHub Repositories. For validation, it uses the same underlying library as the monokle-cli, allowing you to visually discover validation errors in your manifests without having to install any tools or run any commands. For example, navigating to one of the resources in the above repository shows the following:

file explorer view

A validation panel on the left allows you to enable/disable any validation just as you would in the configuration file described earlier immediately showing the update of error information in your manifests:

Kubernetes resource validation dashboard

### Real-time debugging Custom Validators

Monokle Cloud has one more trick up its sleeve in regards to custom validators - it can connect to the local development of your validator plugin and allow you to debug it in real-time - while you code it. 

Provided you’ve scaffolded your plugin using our [create-monokleplugin toolkit](https://github.com/kubeshop/monokle-core/tree/main/packages/create-monokle-plugin) - just run the following command

`npm run dev`

in your plugin folder - which will start a local server that you can connect to to Monokle Cloud in the validation panel:

Kubernetes Plugin Marketplace

## What about Monokle Desktop?

[Monokle Desktop](https://github.com/kubeshop/monokle) currently performs validations with code that was used to extract the monokle validation library, but unfortunately hasn’t transitioned to use the actual library itself (yeah, we know..) - this will be fixed in the next major release giving the same level of validation flexibility consistently across all tools in the Monokle ecosystem.

## Give it a try

That’s it - hopefully you’re intrigued enough to try it out, either as your initial attempt at resource validation or as a complement to your existing tooling, and  let us know what you think on our Discord Server.

Happy YAMLing...!

Related Content

Stay in the Loop

Get Monokle’s monthly newsletter direct to your inbox.

Or join the Monokle Community in one of these channels