feat: dorikin - Kubernetes configuration drift detector by indrasvat · Pull Request #1 · indrasvat/dorikin

indrasvat · 2026-01-07T08:35:53Z

Summary

Dorikin is a Kubernetes configuration drift detector that compares desired manifests against live cluster state. It provides both a CLI for CI/CD integration and an interactive TUI for exploration and debugging.

Core Features

Real-time drift detection — Compares YAML manifests against live cluster state with smart field filtering
Interactive TUI — Navigate resources, view diffs, filter by status (AE86 Panda Trueno themed)
Multiple output formats — Table, JSON, YAML, or quiet mode for scripting
HPA-aware comparison — Automatically skips spec.replicas for HPA-managed workloads
Helm support — Scan Helm charts directly with --helm-values and --helm-set overrides
Kustomize support — Scan Kustomize overlays directly with --kustomize
Quantity normalization — Treats equivalent K8s quantities as equal (128Mi = 134217728, 500m = 0.5)
Content-based matching — Matches arrays by key field (containers by name, not index)
Configuration file — .dorikin.yaml for custom ignore paths and resource-specific rules
Auto-refresh — Continuous monitoring with configurable intervals

Drift Status Types

Status	Description
`IN_SYNC`	Resource matches manifest
`DRIFTED`	Resource exists but fields differ
`MISSING`	Defined in manifest, absent from cluster
`EXTRA`	Exists in cluster, not in manifests
`ERROR`	Fetch or comparison failed

Loader Support

Loader	Command	Description
Raw YAML	`dorikin scan ./manifests/`	Direct YAML files
Helm	`dorikin scan --helm ./chart/`	Helm charts with values/set
Kustomize	`dorikin scan --kustomize ./overlay/`	Kustomize overlays

Test Track

Includes a local testing environment using Colima + k3s with pre-built drift scenarios:

make track-setup    # Create test environment
make track-scan     # Run drift scan
make track-drift    # Apply drift scenarios
make track-tui      # Launch interactive TUI

Test Plan

make ci passes (344 tests, lint clean)
Test track validates all drift detection scenarios
HPA-aware detection verified with StatefulSet and Deployment HPAs
Helm loader tested with values files and --set overrides
Kustomize loader tested with overlays
Quantity normalization verified (128Mi = 134217728 bytes)
Content-based array matching verified (env var reordering)
Configuration file loading tested with custom ignore paths

Convert all numeric types to float64 before comparison since JSON unmarshaling returns numbers as float64 while YAML keeps integers. This eliminates false positives from type mismatches.

- Press 'r' for manual refresh - Press 'a' to toggle auto-refresh (default 5s interval) - Add --refresh-interval flag to configure interval

Fix HPA minReplicas to match deployment replicas (3) to prevent HPA-induced drift at baseline.

Include features, installation, CLI reference, TUI controls, test track instructions, and roadmap.

Explains comparison algorithm, field filtering, type normalization, limitations (HPA, ranges, ordering), and future improvements.

Skip spec.replicas comparison for resources managed by HPAs. Supports Deployments, StatefulSets, and ReplicaSets. Modes: --hpa-aware=manifests (default), cluster, disabled

- Load config from .dorikin.yaml (walks up directory tree) - Global and resource-specific ignore paths - extend_defaults option to include/replace built-in ignores - CLI flags override config file settings

- Add VHS tape files for generating demo recordings - Add demo.gif showing tmux split-pane live drift detection - Update README with demo GIF in Overview section - Add `make demo` target for regenerating the GIF

- Use relative paths for portability - Enable auto-refresh with 'a' key press - Remove temporary test tape file

- Add dorikin-branded status bar (jade green badge, amber LIVE indicator) - Add jade green pane borders for active pane - Add demo-tui make target for quick TUI launches - Document VHS tape format learnings in CLAUDE.md - Add helper script for pane initialization

- Use conditional pane-border-format with correct pane-base-index (1, not 0) - Add dedicated init scripts for left/right pane titles - Document tmux pane-base-index gotcha in CLAUDE.md - Left pane shows "test track", right pane shows "dorikin tui"

- Create common.go with ScanFlags struct and shared initialization - Export ParseHPAAwareMode and BuildLoader for reuse - Add BuildScanContext to handle common setup logic - Reduce scan.go from 205 to 75 lines - Reduce ui.go from 155 to 69 lines - Add CLI tests (39.8% coverage, up from 0%)

- Quantity normalization: Treat 128Mi = 134217728 bytes, 500m = 0.5 CPU Uses k8s.io/apimachinery/pkg/api/resource for semantic comparison - Content-based array matching: Match containers, env, volumes, etc. by key field (name, containerPort, port) instead of by index - Prevents false positives when array order changes or quantities use different but equivalent representations - Update test track with Q/R drift scenarios to exercise new features - Update docs to reflect implemented features (344 tests, 80%+ coverage)

…a test)

indrasvat added 30 commits January 6, 2026 20:22

chore: add gitignore

c65e5fd

feat: add dorikin logo

1ca9242

feat: bootstrap project with cobra CLI

e59f9bb

chore: add Makefile, golangci-lint config, CI workflow

3f13586

feat: add core API types for drift detection

c1a366f

feat: add Kubernetes client with concurrent fetch

0355a65

feat: add manifest loader with YAML parsing

1463070

feat: add drift detector engine with comparison and reporting

61ee00d

feat: add TUI with AE86 Panda Trueno styling

a09206d

feat: add CLI commands (scan, ui, version) and test track

3ccf8ba

fix: normalize numeric types for accurate drift comparison

751818b

Convert all numeric types to float64 before comparison since JSON unmarshaling returns numbers as float64 while YAML keeps integers. This eliminates false positives from type mismatches.

feat: add JSON, YAML, and quiet output formats for scan command

945d9ee

feat: add manual and auto-refresh to TUI

cc8fdfa

- Press 'r' for manual refresh - Press 'a' to toggle auto-refresh (default 5s interval) - Add --refresh-interval flag to configure interval

chore: update test track manifests

0bbd481

Fix HPA minReplicas to match deployment replicas (3) to prevent HPA-induced drift at baseline.

docs: add comprehensive README

b22a6e2

Include features, installation, CLI reference, TUI controls, test track instructions, and roadmap.

chore: expand gitignore for Go project

6b1841d

docs: add drift detection algorithm documentation

d4ca3ef

Explains comparison algorithm, field filtering, type normalization, limitations (HPA, ranges, ordering), and future improvements.

feat: add HPA-aware drift detection

099121f

Skip spec.replicas comparison for resources managed by HPAs. Supports Deployments, StatefulSets, and ReplicaSets. Modes: --hpa-aware=manifests (default), cluster, disabled

feat: add config file support (.dorikin.yaml)

3b17db2

- Load config from .dorikin.yaml (walks up directory tree) - Global and resource-specific ignore paths - extend_defaults option to include/replace built-in ignores - CLI flags override config file settings

docs: update drift-detection with config file and HPA sections

eee4e0b

docs: replace tagline with Tsuchiya quote and badge

d3a47fb

feat: add demo GIF showing live drift detection

8691c59

- Add VHS tape files for generating demo recordings - Add demo.gif showing tmux split-pane live drift detection - Update README with demo GIF in Overview section - Add `make demo` target for regenerating the GIF

feat: update demo with working live drift detection

f713e4d

- Use relative paths for portability - Enable auto-refresh with 'a' key press - Remove temporary test tape file

fix: correct pane titles in demo GIF

f068aae

- Use conditional pane-border-format with correct pane-base-index (1, not 0) - Add dedicated init scripts for left/right pane titles - Document tmux pane-base-index gotcha in CLAUDE.md - Left pane shows "test track", right pane shows "dorikin tui"

fix: upgrade golangci-lint-action v6 to v7 for lint v2 support

9c13934

fix: migrate golangci-lint config to v2 format

086c2bf

fix: correct golangci-lint v2 config schema

1a19a4b

chore: add test dependencies (teatest, golden, testify)

b433bda

test: add testinit package for CI color profile

ffdd69a

indrasvat added 23 commits January 7, 2026 17:41

test: add loader tests with fixtures (9 table-driven tests)

3e1f4ae

test: add TUI model tests (24 table-driven tests)

f88783c

chore: add lefthook for pre-push CI hooks

6b2b2ab

chore: add gotestsum for prettier test output

ed1426e

chore: add hivis icons and test-dots target

8b33f9f

style: fix formatting in comparator_test.go

b41a085

ci: simplify workflow to use make ci

a61068c

ci: use make tools for CI dependencies

b5d7673

fix: correct golangci-lint v2 module path

357b2b6

fix: use minimal tools-ci target for GitHub Actions

43ff219

fix: add gotestsum to tools-ci target

0167350

docs: update roadmap with implemented features

25cd15b

feat: add HelmLoader and KustomizeLoader implementations

cff54f3

test: add unit tests for HelmLoader and KustomizeLoader

4e5668b

chore: add test track fixtures for Helm and Kustomize

a2c8ebc

feat: add --helm and --kustomize CLI flags

6151044

chore: add Helm and Kustomize test track scripts

9fedde0

docs: add Helm and Kustomize documentation

80a898d

fix: add Helm release metadata to default ignore paths

2bc862b

docs: add quantity normalization and content-based matching to features

946db6c

feat: add GoReleaser and release pipeline (darwin/arm64 only for alph…

261e6ae

…a test)

indrasvat force-pushed the create-dorikin branch from a88ab5f to 4c2e44c Compare January 8, 2026 04:44

indrasvat force-pushed the main branch 2 times, most recently from f0ebe6a to 438a7c9 Compare January 8, 2026 04:51

indrasvat force-pushed the create-dorikin branch from 4c2e44c to 261e6ae Compare January 8, 2026 04:51

chore: enable all platforms and remove test branch trigger

00625e0

indrasvat merged commit 2a03d14 into main Jan 8, 2026
6 checks passed

indrasvat deleted the create-dorikin branch January 8, 2026 06:15

Navigation Menu

Repository navigation

feat: dorikin - Kubernetes configuration drift detector - #1

feat: dorikin - Kubernetes configuration drift detector#1
indrasvat merged 60 commits into
mainfrom
create-dorikin

indrasvat commented Jan 7, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

indrasvat commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Core Features

Drift Status Types

Loader Support

Test Track

Test Plan

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

indrasvat commented Jan 7, 2026 •

edited

Loading