Kubeconform Pre-Commit

pre-commit hooks for validating Kubernetes manifests with kubeconform, including rendered Kustomize overlays.

Provisioning

The hooks work with upstream pre-commit 3.0.0 or later and prek 0.3.6 or later. The hook manager provisions an isolated environment with the pinned Go toolchain, kubeconform, kustomize, and this hook repository, so no manual Go, Python, Docker, or PATH setup is needed. The first installation uses the network; later runs reuse the cached environment. kubeconform schema sources can still use the network, depending on the flags you configure.

Use the hooks

Validate manifest files

Use v0.2.0 or later, the first release with the Go implementation; v0.1.0 is the former Python hook.

repos:
  - repo: https://github.com/neteye-platform/kubeconform-precommit
    rev: v0.2.0
    hooks:
      - id: kubeconform
        files: ^manifests/
        args:
          - -strict
          - -kubernetes-version
          - "1.36.2"

The plain hook is native kubeconform: its configured arguments are passed to kubeconform exactly, and the hook manager supplies matching YAML and JSON filenames. kubeconform rejects files that are not Kubernetes manifests (for example .pre-commit-config.yaml or renovate.json), so restrict the hook with files or exclude. See the kubeconform flags.

Pin -kubernetes-version to the Kubernetes version targeted by your cluster (1.36.2 above is only an example). This makes the target version explicit, but kubeconform's default schemas are still fetched from the master branch of their upstream repository, so their contents can change. For fully reproducible validation, point -schema-location at schemas pinned to an immutable commit, or at a local schema snapshot.

Build and validate Kustomize overlays

repos:
  - repo: https://github.com/neteye-platform/kubeconform-precommit
    rev: v0.2.0
    hooks:
      - id: kubeconform-kustomize
        args:
          - overlays/development
          - overlays/production
          - --
          - -strict
          - -schema-location
          - https://example.invalid/schemas/{{.ResourceKind}}.json

kubeconform-kustomize has pass_filenames: false; configure every overlay path explicitly or use standard non-recursive filepath globs:

args:
  - overlays/*
  - --
  - -strict

The wrapper (not a shell) expands glob targets deterministically before passing each resulting path to kustomize build; exact paths, including nonexistent ones, are passed literally. A target containing *, ?, or [ is a pattern. Unmatched or malformed patterns exit 2; ** has no special recursive extension. The first -- separates overlay paths from native kubeconform arguments. The separator is optional; without it, every argument is an overlay. Arguments after it are forwarded exactly as configured (including spaces within one YAML string), without shell parsing.

The rendered output of kustomize build is always what kubeconform validates, through stdin. Arguments after -- must therefore be kubeconform flags: positional file or folder inputs, -h, and -v are rejected with exit 2, because they would make kubeconform skip the rendered overlay.

kubeconform runs once per overlay, so with more than one overlay the json, junit, and tap output formats are rejected with exit 2: their separate reports cannot be combined into one valid document. Use text or pretty, or configure a single overlay per hook.

The public Kustomize hook intentionally has no file-type filter because a generator can produce non-YAML source files. Consumers that want selective execution can add a files regular expression in their own hook configuration.

Migrating --kubeconform-args

For the plain hook, replace the old two-string, whitespace-split argument style:

- id: kubeconform
  args:
    - --kubeconform-args
    - "-strict -ignore-missing-schemas"

with native discrete kubeconform arguments:

- id: kubeconform
  args:
    - -strict
    - -ignore-missing-schemas

For Kustomize, replace:

- id: kubeconform-kustomize
  args:
    - overlays/development
    - --kubeconform-args
    - "-strict -ignore-missing-schemas"

with explicit overlay and native argument boundaries:

- id: kubeconform-kustomize
  args:
    - overlays/development
    - --
    - -strict
    - -ignore-missing-schemas

Exit behavior

For the Kustomize wrapper, no overlays prints usage and exits 2. It resolves both tools before processing overlays, runs kustomize build for each overlay, and passes the exact rendered bytes to kubeconform stdin. It continues after build or validation failures and exits 1 if any overlay failed; otherwise it exits 0. Kubeconform flags after -- are passed as exact native arguments; positional inputs, -h, and -v exit 2 before any overlay is built.

Development

prek run --all-files
testdata/smoke-test.sh prek
testdata/smoke-test.sh pre-commit

prek run covers formatting, golangci-lint, go test, and manifest validation. The smoke test runs both public hooks from this checkout's HEAD commit against the fixtures in testdata/, so commit changes before running it.

This is a Go project; it has no Python or uv package project.

Security

Report vulnerabilities according to the security policy.

License

This project is dual-licensed under MIT or Apache-2.0. You may choose either license; see LICENSE-MIT and LICENSE-APACHE.