@monokle/cli

Welcome to Monokle CLI

Monokle CLI is a command-line interface for static analysis of Kubernetes resources.

Use it to prevent misconfigurations within Kustomize, Helm or default Kubernetes resources. The output is available as a SARIF file which you can upload to GitHub CodeScan.

Monokle CLI includes built-in validators for

• YAML Syntax
• Kubernetes Schema compliance
• Resource links between Kubernetes resources
• OPA Security policies

Under the hood it uses @monokle/validation which allows you to configure validation rules extensively.

Check out the announcement blog-post for an overview of all features.

Table of contents

• Installation
• Usage
  • Validate a YAML file
  • Validate a directory
  • Validate a templated Helm chart
  • Validate a Kustomize build
  • Frameworks
  • Generate SARIF analysis
• Configuration
  • Command-line arguments
  • @monokle/validation rules
  • Custom validators
• GitHub Action
• Docker

Installation

You can install the CLI using brew (if you're on MacOS)

brew install kubeshop/monokle/monokle-cli

or as an NPM package (more installers coming up...).

npm install --global @monokle/cli

(We recommend using the LTS NodeJs version)

Usage

Once installed, using the CLI is straight-forward.

Validate a YAML file

monokle validate bundle.yaml

Validate a directory

This will recursively scan all YAML files and parse them as plain Kubernetes resources.

monokle validate k8s-dir

Validate a templated Helm chart

helm template helm-dir | monokle validate -

Validate a Kustomize build

kustomize build kustomize-dir/overlays/local | monokle validate -

Frameworks

Monokle CLI supports predefined sets of rules called frameworks, which allow you to quickly run Monokle validation without the need for additional configuration.
By using a framework, you can easily perform comprehensive validations based on established best practices and industry standards.

When using a framework, you don't have to configure the monokle.validation.yaml file manually.
Simply specify the desired framework using the --framework or --fw CLI arguments, and Monokle CLI will automatically apply the corresponding set of rules.

Available frameworks:

• pss-restricted
• pss-baseline
• nsa

Using frameworks is an excellent way to get started quickly with Monokle CLI and perform comprehensive validations without the need for extensive configuration.
If you prefer a more customized validation, you can still configure the monokle.validation.yaml file with your own rules.

Here's an example of how to use the --framework argument:

monokle validate k8s-dir --framework pss-restricted

Generate SARIF analysis

The Monokle CLI can output its results in SARIF format.

monokle validate --output sarif k8s-dir > results.sarif

Afterwards you could use VSC's SARIF Viewer or other tools to inspect the results.

Configuration

Command-line arguments

You can use --help to access help information directly from the CLI.

@monokle/validation rules

The Monokle CLI looks for a Monokle Validation configuration file at ./monokle.validation.yaml. You can change this by using the --config flag.

All rules are enabled by default and are described in the Monokle Validation configuration documentation.

Example

plugins:
  yaml-syntax: true
  kubernetes-schema: true
rules:
  yaml-syntax/no-bad-alias: "warn"
  yaml-syntax/no-bad-directive: false
  open-policy-agent/no-last-image: "err"
  open-policy-agent/cpu-limit: "err"
  open-policy-agent/memory-limit: "err"
  open-policy-agent/memory-request: "err"
settings:
  kubernetes-schema:
    schemaVersion: v1.24.2

Custom validators

It is easy to extend the Monokle CLI with custom validators that can be shared with others using our Monokle Community Plugins repository.

GitHub Action

The Monokle GitHub Action can be used to validate your resources as part of your CI/CD pipelines on GitHub

Docker

You can use the Docker image monokle-cli:latest to run the Monokle CLI in a containerized environment.
This can be particularly useful for integrating Monokle into CI/CD pipelines or other automated systems.

To run the Docker image, you can use the docker run command. The Monokle CLI arguments can be passed directly to the Docker run command. For example:

docker run -v /path/to/input:/input -e CONFIG_FILE=my-validation-config.yaml monokle-cli:latest validate /input

In this command:

• -v /path/to/input:/input mounts a directory from your host system to the /input directory inside the Docker container.
• -e CONFIG_FILE=my-validation-config.yaml sets an environment variable inside the Docker container. If this environment variable is set, the Docker container will use the specified file as the Monokle validation configuration.
• validate /input is the command that will be passed to the Monokle CLI. You can replace this with any command you want to run with the Monokle CLI.