celvet

celvet is a multitool for linting CRDs (CustomResourceDefinition) in Kubernetes. celvet also provides particular insight into validation rules, checking that they do not exceed the resource constraints provided by Kubernetes' API server. The tool is deliberately made to be useful both in an ad-hoc fashion by developers in addition to being part of a CI/CD pipeline, so celvet supports output in JSON in addition to machine-readable text.

What does celvet catch?

• CRD parsing errors - celvet will early exit if it finds that a CRD contains YAML/JSON syntax errors.
• Missing limits on variable-length fields - maxLength, maxItems, etc.
• Validation rule parsing errors - if celvet has issues parsing a validation rule, it will output the errors.
• Exceeding resource constraints for validation rules - if a validation rule exceeds the per-rule cost budget, celvet will output an error. Additionally, if the sum total of rules on the CRD exceed the per-CRD cost budget, celvet will output an error there as well.

Installing

celvet can be installed with go install:

go install github.com/DangerOnTheRanger/celvet/cmd/celvet@latest

Usage

celvet crd-file

If celvet finds any linting errors, it will print them to stdout and return a non-zero error code. For example, given one of the example CRDs from the k8s documentation, celvet will output:

string "spec.validation.openAPIV3Schema.properties[spec].properties[cronSpec]" missing maxLength
string "spec.validation.openAPIV3Schema.properties[spec].properties[image]" missing maxLength

The -o/--output option can be used to change the output format to JSON if json is passed to the flag; text is the default option but can be explicitly passed. The same file but with -o json passed will give the following (the data has been pretty-printed here for readability):

{
  "limitErrors": [
    {
      "path": "spec.validation.openAPIV3Schema.properties[spec].properties[image]",
      "type": "string"
    },
    {
      "path": "spec.validation.openAPIV3Schema.properties[spec].properties[cronSpec]",
      "type": "string"
    }
  ]
}

Fixing linter errors

The different types of linter errors that are caught and how to fix them are explained below. "Type" refers to the key in the JSON output used for that error type.

Type	Fix
limitErrors	Add a maxLength to the schema if the error is on a string, maxItems for arrays, or maxProperties for an object/map.
costErrors	The validation rule exceeds the allowable per-rule computation limit. Optimize the expression, and/or lower limits on the schema of any variable-length data it processes (if there are no limits, adding them may remove the cost error).
compileErrors	Fix the compilation/syntax error that was found on the associated validation rule.
internalErrors	Internal errors are caused by internal/non-linting related failures. These are not meant to be fixable by end users, and their presence likely is indicative of a bug.