Version: Next (unreleased)

Configuration

One config model, four layers of precedence.

kubediag configuration is intentionally shallow. The important behavior is precedence: flags override environment variables, environment variables override the config file, and the config file overrides defaults. That makes the tool predictable in local shells, CI jobs, and incident automation.

Flags > env > file > defaults~/.config/triage/config.yamlSame config across scopes

Defaults

Start from safe general behavior

Text output, low confidence threshold, and a modest finding cap are meant to be useful without any configuration.

File config

Use a config file for workstation preferences

Good for persistent output preferences, namespace exclusions, or rule enable/disable lists.

Environment

Use env vars for automation and wrappers

Good when the invoking environment wants to shape output or thresholds without editing files.

Flags

Use flags for incident-specific overrides

Best when the diagnosis needs to be narrower, quieter, or differently formatted right now.

Find the active config

Inspect the resolved path and the resolved values.

These commands are the fastest way to debug configuration behavior before you start guessing about precedence.

kubediag config path
kubediag config view

`config view` includes provenance, which makes it obvious whether a value came from a flag, env var, file, or default.

Reference config

# Output format: text | json | markdown
output: text

# Color mode: auto | always | never
color: auto

# Minimum severity to display: critical | high | medium | low | info
severityMin: info

# Minimum confidence to display: high | medium | low
confidenceMin: low

# Maximum number of findings to render (0 = unlimited)
maxFindings: 20

# Include related events in output
includeEvents: true

# Include related resources (services, pvcs, endpoints) in output
includeRelated: true

# Overall Kubernetes API timeout
timeout: 15s

rules:
  disabled: []
  enabled: []

namespaces:
  exclude: [kube-system, kube-public]

High-signal knobs

Key	What it changes
`output`	Selects terminal text, JSON, or markdown as the renderer.
`severityMin`	Filters out lower-severity findings early in the output.
`confidenceMin`	Filters out lower-confidence diagnoses when you want a stricter signal.
`maxFindings`	Caps output size on dense namespace and cluster scans.
`includeEvents`	Controls whether event context is folded into evidence.
`includeRelated`	Controls whether adjacent resources are included when relevant.
`rules.disabled` / `rules.enabled`	Lets you trim or constrain the active rule set.
`namespaces.exclude`	Prevents noisy namespaces from dominating broad scans.

Environment variable mapping

Env var	Config key
`KUBEDIAG_OUTPUT`	`output`
`KUBEDIAG_COLOR`	`color`
`KUBEDIAG_SEVERITY_MIN`	`severityMin`
`KUBEDIAG_CONFIDENCE_MIN`	`confidenceMin`
`KUBEDIAG_MAX_FINDINGS`	`maxFindings`
`KUBEDIAG_TIMEOUT`	`timeout`
`NO_COLOR`	Disables color by convention

When to use flags instead

Use flags when the value is specific to one run, such as:

raising --severity-min during a noisy incident
switching to -o json for one automation step
lowering --max-findings when only the top-ranked items matter
pointing at a temporary config file with --config

The fewer persistent surprises the tool has, the more trustworthy it is under pressure. That is why kubediag keeps the config surface small and the precedence model explicit.