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 on GitHub - 100% open-source - MIT licensed.
## Jumping in…
Enough talk - let’s jump straight in. If you're on MacOS, install Monokle-CLI with brew:
`brew install kubeshop/monokle/monokle-cli`
on other platforms 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:
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.
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:
Going to the details of a failed check will show
## 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:
And here you can see it in action in the Monokle Cloud UI (more on that below…)
## 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:
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:
### 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-monokle-plugin 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:
## 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...!
Join the Monokle Community in one of these channels:
Subscribe to our monthly newsletter to stay up to date with all-things Monokle.
.png)
