kdiff

a command-line tool that diffs two Kubernetes manifests and tells you what changed and more importantly, whether any of those changes are dangerous

$ kdiff diff before/deployment.yaml after/deployment.yaml

modified   Deployment production/api
  spec.replicas                                           3 → 1
  spec.strategy.type                                      RollingUpdate → Recreate
  spec.template.spec.containers.api.image                 api:v1.2.3 → api:latest
  spec.template.spec.containers.api.env.LOG_LEVEL         info → (removed)

risk flags:
  [HIGH]   replica-decreased — replicas decreased from 3 to 1 (spec.replicas)
  [HIGH]   strategy-type-changed — deploy strategy changed "RollingUpdate" → "Recreate" (spec.strategy.type)
  [HIGH]   image-unpinned — image "api:latest" uses the :latest tag (spec.template.spec.containers.api.image)
  [HIGH]   env-var-removed — environment variable removed: LOG_LEVEL (spec.template.spec.containers.api.env.LOG_LEVEL)

Install

go install github.com/am-miracle/kdiff@latest

Usage

# compare two files
kdiff diff before.yaml after.yaml

# compare two directories (all .yaml and .yml files, alphabetical order)
kdiff diff before/ after/

# output JSON for CI pipelines
kdiff diff before.yaml after.yaml --output json

# force color when piping to less or another tool
kdiff diff before.yaml after.yaml --color

What it checks

kdiff accepts single files or directories. For directories it loads every .yaml and .yml file in alphabetical order and compares the full resource set.

Every modified resource shows the exact field paths that changed with before and after values. On top of that, the risk analyzer checks each change against a set of rules and reports anything operationally dangerous.

Rule	Severity	What triggers it
resource-deleted	HIGH	A resource present in before is absent in after
replica-decreased	HIGH	spec.replicas went down
image-unpinned	HIGH	Image tag is :latest or missing entirely
env-var-removed	HIGH	An environment variable was removed
probe-removed	HIGH	A liveness, readiness, or startup probe was removed
strategy-type-changed	HIGH	Deployment strategy changed to Recreate
volume-mount-removed	HIGH	A volume mount was removed
image-changed	MEDIUM	Container image changed to any new value
resource-limits-changed	MEDIUM	CPU or memory limits or requests changed
termination-grace-period-decreased	MEDIUM	terminationGracePeriodSeconds went down

Output formats

Terminal (default): color-coded, human-readable. Colors are auto-detected and only applied when writing to a real TTY. Use --color to force them on.

JSON (--output json): machine-readable, suitable for CI. The top-level object has two keys: changes and risk_flags.

{
  "changes": [
    {
      "type": "modified",
      "kind": "Deployment",
      "namespace": "production",
      "name": "api",
      "fields": [
        { "path": "spec.replicas", "before": 3, "after": 1 }
      ]
    }
  ],
  "risk_flags": [
    {
      "severity": "HIGH",
      "rule": "replica-decreased",
      "message": "replicas decreased from 3 to 1",
      "path": "spec.replicas"
    }
  ]
}

What it does not do

• No live cluster connection. It reads files only.
• No Helm or Kustomize rendering. Render first, then pass the output to kdiff.
• No recursive directory traversal. Only the top level of a directory is read.