Repository files navigation

Kube API Linter (KAL) is a Golang based linter for Kubernetes API types.It checks for common mistakes and enforces best practices.The rules implemented by the Kube API Linter, are based on theKubernetes API Conventions.

Kube API Linter is aimed at being an assistant to API review, by catching the mechanical elements of API review, and allowing reviewers to focus on the more complex aspects of API design.

Kube API Linter ships as a standalone binary, golangci-lint plugin, and a golangci-lint module.

The binary version of Kube API Linter can be built withmake build or a standardgo build command.

go build -o ./bin ./cmd/golangci-lint-kube-api-linter

The binary builds a custom version ofgolangci-lint with Kube API Linter included as a module.SeeGolangci-lint Moduule for details on configuration of the moduleunderlinter-settings.

To install thegolangci-lint module, first you must havegolangci-lint installed.If you do not havegolangci-lint installed, review thegolangci-lintinstall guide.

You will need to create a.custom-gcl.yml file to describe the custom linters you want to run. The following is an example of a.custom-gcl.yml file:

version:v1.64.8name:golangci-kube-api-linterdestination:./binplugins:-module:'sigs.k8s.io/kube-api-linter'version:'v0.0.0'# Replace with the latest version

Once you have created the custom configuration file, you can run the following command to build the customgolangci-kal binary:

golangci-lint custom

The output binary will be a combination of the initialgolangci-lint binary and the Kube API linter plugin.This means that you can use any of the standardgolangci-lint configuration or flags to run the binary, but may also include the Kube API Linter rules.

If you wish to only use the Kube API Linter rules, you can configure your.golangci.yml file to only run the Kube API Linter:

linters-settings:custom:kubeapilinter:type:"module"description:Kube API LInter lints Kube like APIs based on API conventions and best practices.settings:linters:{}lintersConfig:{}linters:disable-all:trueenable:    -kubeapilinter# To only run Kube API Linter on specific pathissues:exclude-rules:    -path-except:"api/*"linters:        -kubeapilinter

If you wish to only run selected linters you can do so by specifying the linters you want to enable in thelinters section:

linters-settings:custom:kubeapilinter:type:"module"settings:linters:disable:            -"*"enable:            -requiredfields            -statusoptional            -statussubresource

The settings for Kube API Linter are based on theGolangCIConfig struct and allow for finer control over the linter rules.

If you wish to use the Kube API Linter in conjunction with other linters, you can enable the Kube API Linter in the.golangci.yml file by ensuring thatkubeapilinter is in thelinters.enabled list.To provide further configuration, add thecustom.kubeapilinter section to yourlinter-settings as per the example above.

Where fixes are available within a rule, these can be applied automatically with the--fix flag.

golangci-kube-api-linter run path/to/api/types --fix

The Kube API Linter can also be used as a plugin forgolangci-lint.To do this, you will need to install thegolangci-lint binary and then install the Kube API Linter plugin.

More information about golangci-lint plugins can be found in thegolangci-lint plugin documentation.

go build -buildmode=plugin -o bin/kube-api-linter.so sigs.k8s.io/kube-api-linter/pkg/plugin

This will create akube-api-linter.so file in thebin directory.

Thegolangci-lint configuration is similar to the module configuration, however, you will need to specify the plugin path instead.

linters-settings:custom:kubeapilinter:path:"bin/kube-api-linter.so"description:Kube API LInter lints Kube like APIs based on API conventions and best practices.original-url:sigs.k8s.io/kube-api-lintersettings:linters:{}lintersConfig:{}

The rest of the configuration is the same as the module configuration, except the standardgolangci-lint binary is invoked, rather than a custom binary.

Since VSCode already integrates withgolangci-lint via theGo extension, you can use thegolangci-kal binary as a linter in VSCode.If your project authors are already using VSCode and have the configuration to lint their code when saving, this can be a seamless integration.

Ensure that your project setup includes building thegolangci-kube-api-linter binary, and then configure thego.lintTool andgo.alternateTools settings in your project.vscode/settings.json file.

{"go.lintTool":"golangci-lint","go.alternateTools": {"golangci-lint":"${workspaceFolder}/bin/golangci-kube-api-linter",    }}

Alternatively, you can also replace the binary with a script that runs thegolangci-kube-api-linter binary,allowing for customisation or automatic copmilation of the project should it not already exist.

{"go.lintTool":"golangci-lint","go.alternateTools": {"golangci-lint":"${workspaceFolder}/hack/golangci-lint.sh",    }}

New linters can be added by following theNew Linter guide.

For a complete list of available linters and their configuration options, seedocs/linters.md.

KAL is licensed under the Apache License, Version 2.0. SeeLICENSE for the full license text.