English | νκ΅μ΄
Know what to change before changing Kubernetes.
Inspect manifests, Helm charts and read-only snapshots with a CLI that compares current state β recommended state β next action. Use official target-version schemas, traceable evidence, offline analysis and local MCP tools.
Download Β· Quick start Β· Report preview Β· Command reference Β· Roadmap
Alpha software. Analysis is offline by default, with no telemetry. Explicit collection contacts your selected API server; opt-in external authentication may also contact identity services. Reports show partial coverage and never apply changes automatically.
- β¨ Features
- π Report preview
- π Quick start
- π¦ Installation
- π οΈ Commands at a glance
- π Command reference
- π€ Local MCP and local models
- π§ Build and development
- π Scope and evidence
- π¬ Development and feedback
- πΊοΈ Roadmap
- π Release notes
- π License
| Feature | What you can do |
|---|---|
| π Manifest & API inspection | Find schema errors and deprecated/removed APIs using official Kubernetes 1.16β1.37 .0 schemas, selected exact patches and supplied local CRDs. |
| π― Actionable recommendations | Review required, conditional and optional actions with current/recommended comparisons, reasons and verification steps. |
| βοΈ Helm & manifest drift | Render local charts and compare desired resources with explicitly scoped, GET-only snapshots. |
| πͺ Upgrade planning | Review minor-version steps and workload API changes before upgrading. Provider availability and runtime compatibility need separate verification. |
| βοΈ Cloud migration review | Inventory EKS/AKS/GKE storage, load balancer and identity dependencies. Cross-cloud provisioning and data migration are not performed; AKS review scaffolds are available separately. |
| π Network intent analysis | Inspect Service/Ingress exposure, NetworkPolicy isolation intent and existing Hubble flows without active probes. |
| π Shareable reports | Read terminal summaries or export JSON, Markdown and standalone HTML with evidence and unchecked areas. |
| π€ Local MCP integration | Expose scoped inspection tools to MCP clients, including clients using local DeepSeek/Ollama models. No built-in LLM calls. |
| π Offline analysis | Analyze local inputs without telemetry or automatic downloads. Explicit collection contacts only the selected Kubernetes API server. |
An actual generated HTML review: required actions first, current and recommended settings side by side, with source hashes and original evidence available on demand.
HTML file Β· Markdown report Β· Example input
Download the HTML file and open it locally. It loads no external fonts or scripts. The comparison view shown above is available from v0.2.0-alpha.3.
- Download the matching archive from Releases, verify its checksum and extract it.
- Add the binary to PATH, or run
./kubewiserfrom the extracted folder (.\kubewiser.exeon Windows). - Inspect your manifests and open the report. No Go, Helm or kubectl installation is required.
kubewiser --version
kubewiser scan files --target-version 1.37 --recommend --format text ./deploy
kubewiser scan files --target-version 1.37 --recommend --format html ./deploy > report.htmlFor a legacy CronJob, the terminal review looks like this (selected lines from actual output):
$ kubewiser scan files --target-version 1.37 --format text docs/examples/manifest.yaml
Inspection review
Target Kubernetes 1.37 Β· Resources 1 Β· Schema checked 0
...
Required: 1 | Conditional: 0 | Optional: 0
1. [Required] Migrate the Kubernetes API (KW-API-REMOVED)
batch/v1beta1/CronJob//example-legacy-job
Current: apiVersion: batch/v1beta1
Recommended: batch/v1
...Findings return exit code 1 while still producing a report. Always review unchecked areas too. Add --lang ko for Korean review explanations; original evidence can remain English.
| Platform | Archive suffix |
|---|---|
| Linux Intel/AMD Β· ARM64 | linux_amd64.tar.gz Β· linux_arm64.tar.gz |
| macOS Intel Β· Apple Silicon | darwin_amd64.tar.gz Β· darwin_arm64.tar.gz |
| Windows 10+ 64-bit Β· 32-bit | windows_amd64.zip Β· windows_386.zip |
Filenames also include the release version. kubewiser and kubewise are equivalent commands. Windows ZIPs contain one EXE and install.ps1; running the installer registers both names and the user PATH.
.\install.ps1
kubewiser scan files --target-version 1.37 --format html .\deploy | Out-File -Encoding utf8 report.html
Start-Process .\report.htmlSee installation details for checksums, OS validation boundaries and setup.
| Command | Purpose |
|---|---|
scan files |
Inspect a manifest file or directory |
scan cel |
Evaluate local CRD validation and transition rules |
scan helm |
Render and inspect a local chart |
collect |
Snapshot an explicit cluster context and namespace |
scan snapshot |
Validate saved resources for a target version |
diff |
Compare manifests or a chart with a snapshot |
plan upgrade |
Review minor upgrade steps and actions |
plan aks / generate |
Review an AKS project profile / create local draft templates |
scan path |
Evaluate supplied ingress and egress policy intent for two Pods |
scan network |
Inspect configuration and existing flows |
plan migrate |
Review cloud migration dependencies |
mcp |
Serve scoped local inspection tools |
versions / --version / --help |
Schema inventory / binary information / help |
Expand the sections below for commands, actual terminal output and exit codes.
kubewiser plan aks --source ./deploy --profile docs/examples/project/aks.json --format html > aks-plan.html
kubewiser generate --profile docs/examples/project/aks.json --output ./new-review-drafts
kubewiser scan path --source ./network-inputs --source-pod team/client --destination-pod team/api --port 8080Project profile, architecture requirements, templates and network path guide. The 1.21 β 1.35 example is an unverified requirement, not an AKS-supported route. Generated Terraform/Helm/manifest files are review scaffolds; no infrastructure operations run.
kubewiser scan files --target-version 1.35.9 ./deploy
kubewiser scan cel --source ./crds-and-resources --format html > cel.html
kubewiser diff --source ./deploy --snapshot ./snapshot.json --crd-defaults --crd-conversion
kubewiser scan path --source ./network-inputs --source-pod team/client --destination-service team/api --port 443 --flows ./hubble.jsonlAuthentication, AKS exported evidence, patch schemas, CEL, image platforms and configured templates. Older terminal excerpts below were captured for alpha.3/alpha.4; diagnostic wording can differ in newer versions.
Every kubewiser command also works as kubewise. Put flags before positional paths. Run the checked-in docs/examples/... examples from the repository root. Replace example paths, context and namespace when using your own inputs. Fixtures are synthetic documentation data; snapshot.json contains one Service and is not a production snapshot. Terminal excerpts below come from actual local CLI runs. echo $? is the POSIX shell exit-code check; in PowerShell use $LASTEXITCODE. MCP is a waiting server, not a report-producing command.
Output formats and saving reports
Markdown/HTML require v0.2.0-alpha.2+. Comparison reviews and --lang en|ko for scan/plan/diff require v0.2.0-alpha.3+. JSON remains unchanged; original evidence wording may remain English even in Korean reviews.
| Format | Purpose | Example |
|---|---|---|
json (default) |
Automation and structured processing | --format json ... > report.json |
text |
Concise terminal summary for direct scan reports | --format text ... |
markdown |
Tables and lists for GitHub or editors | --format markdown ... > report.md |
html |
Standalone browser report, including printing | --format html ... > report.html |
Text reports for scan files/snapshot/helm, diff and plan show current/recommended states and actions. Network and collection text output remains JSON. Markdown/HTML work for scan, diff, plan and collection summaries. versions supports json/markdown/html. MCP always uses structured protocol responses.
kubewiser scan files --target-version 1.37 --format markdown docs/examples/manifest.yaml > report.md
kubewiser scan files --target-version 1.37 --format html docs/examples/manifest.yaml > report.html# Windows PowerShell: preserve Unicode as UTF-8
kubewiser scan files --target-version 1.37 --format html .\deploy | Out-File -Encoding utf8 report.html
Start-Process .\report.htmlHTML includes its CSS and loads no external fonts, scripts or images. Both readable formats retain the JSON report's evidence and unchecked areas and escape input-controlled markup. Reports can still contain sensitive paths, resource names and metadata. Redirection is silent on success: open the saved file to view it. Findings can produce exit code 1 while still saving a complete report.
--help, --version, versions β inspect commands and supported versions
--version identifies the binary; versions lists embedded schema versions, official source URLs, hashes and review dates. Exact bundled patches (1.35.9, 1.36.5, 1.37.1) are preferred; other patches explicitly report the minor .0 fallback.
Terminal example β Long JSON is excerpted to selected fields. Actual output includes additional evidence and unchecked areas.
$ kubewiser --help
Commands: kubewiser or kubewise
--version
versions [--format json|markdown|html]
scan files --target-version VERSION [--recommend] PATH
scan helm --target-version VERSION --release NAME --namespace NS [--values FILE] CHART
...
$ echo $?
0Terminal example β Actual output from a local development build. Release binaries display their own version, commit and platform.
$ kubewiser --version
kubewiser dev (commit unknown; linux/amd64)
$ echo $?
0Terminal example β Long JSON is excerpted to selected fields. Actual output includes additional evidence and unchecked areas.
$ kubewiser versions
[
{
"version": "v1.16.0",
"source": "https://raw.githubusercontent.com/kubernetes/kubernetes/v1.16.0/api/openapi-spec/swagger.json",
"reviewed": "2026-11-15"
}
]
$ echo $?
0scan files β validate YAML/JSON manifests
Inspect a file or directory recursively for schema errors and API deprecation/removal. Add --recommend for conditional readiness/resource recommendations. Supply CRDs alongside custom resources to use local schemas. Review findings, source positions, requirement, severity, source and schema_checked.
Terminal example β Long JSON is excerpted to selected fields. Actual output includes additional evidence and unchecked areas.
$ kubewiser scan files --target-version 1.37 --format text docs/examples/manifest.yaml
Inspection review
Target Kubernetes 1.37 Β· Resources 1 Β· Schema checked 0
Start with required actions, then check whether conditional recommendations apply to your workloads.
Required: 1 | Conditional: 0 | Optional: 0
1. [Required] Migrate the Kubernetes API (KW-API-REMOVED)
batch/v1beta1/CronJob//example-legacy-job
Current: apiVersion: batch/v1beta1
Recommended: batch/v1
Why: Deprecated in 1.21; no longer served from 1.25.
Action: Migrate the resource using the official migration guide, including field and behavior changes. An apiVersion edit alone may be insufficient.
Verify: Re-run this inspection and test the workload in a staging environment.
Location: docs/examples/manifest.yaml:1 /apiVersion
Source: https://kubernetes.io/docs/reference/using-api/deprecation-guide/
NOT VERIFIED (partial coverage):
- Admission, CEL, controller behavior, feature-gate availability and application runtime compatibility are not evaluated
- OpenAPI validation does not replace Kubernetes admission or server semantic validation
- Schemas are pinned to minor .0 releases; patch-specific changes are not inferred
$ echo $?
1scan helm β render and inspect a local chart
Use an unpacked chart with dependencies already vendored locally. --release, --namespace and optional --values fix rendering inputs. No Helm installation, dependency downloads, live lookup or apply is performed. render records chart metadata/capabilities; report contains findings. --api-versions replaces the entire default capability list. Helm values.schema.json validation is skipped.
Terminal example β Long JSON is excerpted to selected fields. Actual output includes additional evidence and unchecked areas.
$ kubewiser scan helm --target-version 1.37 --release app --namespace team docs/examples/chart
{
"render": {
"chart": "demo",
"chart_version": "0.1.0",
"release": "app",
"namespace": "team",
"target_version": "1.37"
},
"report": {
"documents": 1,
"schema_checked": 1,
"findings": [],
"status": "partial"
}
}
$ echo $?
0Additional usage with your own inputs:
kubewiser scan helm --target-version 1.37 --release app --namespace team --values ./values.yaml --format html ./chart > helm-report.htmlcollect β create a read-only snapshot
Requires explicit --kubeconfig, --context, --namespace and a new --output file. This command contacts the selected API server. The output file is always a JSON snapshot; stdout is a summary whose presentation can be Markdown/HTML. Existing snapshots are never overwritten. Secrets are excluded and selected sensitive fields are removed. Exec authentication is blocked by default; --allow-exec-auth /absolute/path explicitly allows a fixed external authentication executable that may contact identity services. See authentication boundaries. Defaults and allowlists are in operational details.
Terminal example β Captured against an empty loopback mock API server, not a real cluster. Only the temporary output path is shown as snapshot.json.
$ kubewiser collect --kubeconfig ./config --context demo --namespace team --qps 10 --output snapshot.json
{
"gaps": [
{
"resource": "coverage",
"reason": "Secrets, custom resources, unlisted kinds and other namespaces are not collected"
}
],
"output": "snapshot.json",
"redacted_fields": 0,
"requests": 13,
"resources": 0
}
$ echo $?
0Additional usage with your own inputs:
kubewiser collect --kubeconfig ./config --context staging --namespace team --include-cluster-resources --qps 1 --max-items 3000 --timeout 3m --output ./snapshot-with-nodes.json --format markdown > collection-summary.mdscan snapshot β inspect saved resources
Validate a saved snapshot against a target version without reconnecting to the cluster. Collection gaps and redacted fields appear in unchecked. Resources absent from the snapshot have not been validated.
Terminal example β Long JSON is excerpted to selected fields. Actual output includes additional evidence and unchecked areas.
$ kubewiser scan snapshot --target-version 1.37 --format text docs/examples/snapshot.json
Inspection review
Target Kubernetes 1.37 Β· Resources 1 Β· Schema checked 1
No findings in the checks performed. Review coverage before deciding that a change is safe.
Required: 0 | Conditional: 0 | Optional: 0
NOT VERIFIED (partial coverage):
- Admission, CEL, controller behavior, feature-gate availability and application runtime compatibility are not evaluated
- OpenAPI validation does not replace Kubernetes admission or server semantic validation
- Schemas are pinned to minor .0 releases; patch-specific changes are not inferred
- coverage: Synthetic documentation fixture: only one Service included
- Redacted fields may not be schema-validated
$ echo $?
0diff β compare desired and observed state
Use exactly one of --source or --chart, plus --snapshot. Namespace defaults to the snapshot namespace. changed means differing values (values are omitted); desired_only_field/observed_only_field indicate fields present on one side. Observed-only fields can be defaults or controller additions. not_observed may reflect missing collection scope or permissions. observed_only_resource is not a deletion recommendation. conversion_unverified means API-version conversion is needed.
Terminal example β Long JSON is excerpted to selected fields. Actual output includes additional evidence and unchecked areas.
$ kubewiser diff --source docs/examples/desired.yaml --snapshot docs/examples/snapshot.json
{
"changes": [
{
"resource": "/Service/team/web",
"path": "/spec/ports",
"type": "changed",
"message": "Declared and observed values differ; values omitted"
}
]
}
$ echo $?
1Additional usage with your own inputs:
kubewiser diff --chart ./chart --target-version 1.37 --release app --values ./values.yaml --snapshot ./snapshot.json --format html > drift.htmlplan upgrade β list upgrade actions
Specify an increasing minor-version range with --from/--to and exactly one of --source or --snapshot. steps lists minor-by-minor progression; actions includes requirements, verification and evidence. Node inputs enable kubelet skew checks. Add-on, application and kernel compatibility still require separate validation.
Terminal example β Long JSON is excerpted to selected fields. Actual output includes additional evidence and unchecked areas.
$ kubewiser plan upgrade --source docs/examples/manifest.yaml --from 1.24 --to 1.26
{
"kind": "upgrade",
"from": "1.24",
"to": "1.26",
"steps": [
"1.25: verify provider/add-on prerequisites, upgrade control plane, then compatible node components, then validate workloads",
"1.26: verify provider/add-on prerequisites, upgrade control plane, then compatible node components, then validate workloads"
],
"actions": [
{
"id": "KW-API-REMOVED",
"resource": "batch/v1beta1/CronJob//example-legacy-job",
"requirement": "required",
"message": "Not served since 1.25; migrate to batch/v1",
"verification": "Re-run target validation and test workload behavior in staging",
"source": "https://kubernetes.io/docs/reference/using-api/deprecation-guide/",
"before_version": "1.26"
}
]
}
$ echo $?
0Additional usage with your own inputs:
kubewiser plan upgrade --snapshot ./snapshot-with-nodes.json --from 1.35 --to 1.37 --format html > upgrade-plan.htmlscan network β inspect intent and existing flows
Read manifests or a snapshot; optionally supply existing Hubble JSON Lines with --flows. exposures shows configured exposure, isolation shows policy isolation intent and observed_flows aggregates observed endpoints, verdicts and times. No probes or agents are started. Configured or observed connectivity is not a reachability guarantee.
Terminal example β Long JSON is excerpted to selected fields. Actual output includes additional evidence and unchecked areas.
$ kubewiser scan network --snapshot docs/examples/snapshot.json --flows docs/examples/hubble.jsonl
{
"exposures": [
{
"resource": "v1/Service/team/web",
"type": "LoadBalancer",
"evidence": "configured exposure, not reachability tested"
}
],
"observed_flows": [
{
"source": "team/web",
"destination": "team/db",
"verdict": "FORWARDED",
"count": 1,
"first_observed": "2026-11-15T00:00:00Z",
"last_observed": "2026-11-15T00:00:00Z"
}
]
}
$ echo $?
0Additional usage with your own inputs:
kubewiser scan network --namespace team --format markdown ./deploy > network-policy.mdplan migrate β inventory cloud dependencies
Choose distinct providers from eks, aks, gke using --from/--to. Review storage, load balancing, workload identity and platform-specific settings. No cloud API calls, provisioning, template generation or data movement occurs. Original manifests retain provider annotations that snapshots redact.
Terminal example β Long JSON is excerpted to selected fields. Actual output includes additional evidence and unchecked areas.
$ kubewiser plan migrate --source docs/examples/desired.yaml --from eks --to aks
{
"kind": "migration",
"from": "eks",
"to": "aks",
"actions": [
{
"id": "KW-MIGRATE-LB",
"resource": "v1/Service/team/web",
"requirement": "required",
"message": "Recreate provider load balancer configuration, annotations and health checks; verify client IP and exposure",
"verification": "Validate target provider configuration and test in staging before cutover",
"source": "https://learn.microsoft.com/en-us/azure/aks/what-is-aks"
}
]
}
$ echo $?
0Additional usage with your own inputs:
kubewiser plan migrate --snapshot ./snapshot.json --from aks --to gke --format html > migration-plan.htmlmcp β serve tools to a local model client
$ kubewiser mcp --input docs/examples/desired.yaml --snapshot docs/examples/snapshot.json --namespace teamNo banner or report is printed while waiting for MCP requests. Configure an MCP-capable client to launch the command, or press Ctrl+C to stop a manual session. Do not redirect it to report.md. Add fixed --chart, --values and --flows paths to enable those inputs. See the local-model details below.
Interpreting results and exit codes
| Field | Meaning |
|---|---|
required |
Required action |
conditional |
Act when the stated condition applies |
optional |
Recommendation based on measured operational needs |
severity |
Error/warning severity, separate from requirement |
source / evidence |
Documentation source and evidence level |
unchecked / gaps |
Unvalidated areas and collection gaps |
status: partial |
Limited inspection coverage, not full compatibility assurance |
Scan exits with 0 for no findings, 1 for findings and 2 for argument/operational errors. Diff returns 1 for changes. Successful collect/plan/network commands return 0 even with actions or gaps. Exit 0 does not prove compatibility. Findings exit code 1 still produces reports. Shell > overwrites existing report files; choose filenames accordingly.
kubewiser mcp --input /absolute/path/deploy --snapshot /absolute/path/snapshot.jsonAn MCP-capable client can connect a local DeepSeek/Ollama model to this stdio server. Kubewiser does not launch or call an LLM. Tools: scan_files, plan_upgrade, plan_migrate, scan_network; compare_drift requires input and snapshot, scan_helm requires --chart. Paths and cluster scope are fixed by the operator at startup, not chosen by the model. Use --namespace when the desired manifests omit it.
Collection is absent by default. Enabling --allow-cluster also requires explicit --kubeconfig, --context, --namespace; collection returns a redacted snapshot to the MCP client. The client/model can transmit received data: use a local-only client configuration if external transmission is prohibited. Paths, hashes, resource names, IPs and remaining snapshot metadata can still be sensitive. Treat chosen charts and manifests as trusted local inputs.
Requires Go 1.26+; CI pins the toolchain in .go-version. Runtime binaries require no Go installation.
go build -o kubewiser ./cmd/kubewiser
go test -race ./...
go vet ./...Third-party dependencies and embedded official schemas are covered by THIRD_PARTY_NOTICES.txt. Reports use format v2; consumers of earlier alpha reports must update their parsers.
Selected exact patch schemas and separate CRD CEL inspection are available; the actual schema version and remaining coverage are reported. Admission webhooks, target feature gates, application/kernel execution and full network reachability require environment evidence. No automatic infrastructure generation or data migration is performed. Numeric CPU/memory sizing needs measurements; this report does not invent values.
Official sources Β· Operational boundaries Β· Report design references
Report reproducible problems through GitHub Issues. Include the command, target version and a small sanitized example. Do not attach kubeconfig credentials, Secrets or unreviewed production snapshots.
Roadmap Β· Release notes Β· License Β· Third-party notices
