Merge pull request #17 from Colvin-Y/codex/helm-upgrade-diagnostics

[codex] Add Helm upgrade failure triage

Author: Colvin-Y

AI_CONTRACT.md

@@ -223,6 +223,20 @@ relationships use `provenance.sourceType=label_evidence`,
 `provenance.state=inferred`, and a numeric confidence. Treat them as strong or
 weak ownership hints until exact Helm release manifest evidence is collected.
 
+For Helm upgrade failures, the diagnostic graph describes current Kubernetes
+state plus Helm metadata already visible in the cluster. It cannot observe Helm
+CLI stderr, chart rendering, values schema validation, repository/client
+authentication, hook execution semantics, or the original failure hidden by
+`--atomic` rollback unless the user provides that output. When Helm evidence is
+present, agents should expect:
+
+- a `helm_cli_output_not_observed` warning
+- a `helm_manifest_evidence_not_collected` warning for label-derived ownership
+- `helm_cli_output` and `helm_release_manifest` entries in `degradedSources`
+- `HelmOwnershipEvidence` / `HelmChartEvidence` entries in `rankedEvidence`
+- `helm_ownership_conflict` conflicts when one resource points at multiple
+  candidate releases
+
 AI-Agent code should assume these meanings are stable, even if the set of returned nodes varies by policy.
 
 ## What AI-Agent code should treat as optional

Makefile

@@ -44,7 +44,7 @@ DAEMON_CONFIG_OVERRIDES = $(CLI_CONFIG_OVERRIDES) $(call make_arg,SERVER_ADDR,ad
 CLI_CONFIG_ARGS = $(if $(CONFIG),--config "$(CONFIG)" $(CLI_CONFIG_OVERRIDES),--kubeconfig "$(KUBECONFIG)" --cluster "$(CLUSTER)" --context-namespaces "$(CONTEXT_NAMESPACES)" --workload-resources "$(WORKLOAD_RESOURCES)" --controller-rules "$(CONTROLLER_RULES)" --bootstrap-timeout "$(BOOTSTRAP_TIMEOUT)")
 DAEMON_CONFIG_ARGS = $(if $(CONFIG),--config "$(CONFIG)" $(DAEMON_CONFIG_OVERRIDES),--kubeconfig "$(KUBECONFIG)" --cluster "$(CLUSTER)" --context-namespaces "$(CONTEXT_NAMESPACES)" --workload-resources "$(WORKLOAD_RESOURCES)" --controller-rules "$(CONTROLLER_RULES)" --addr "$(SERVER_ADDR)" --bootstrap-timeout "$(BOOTSTRAP_TIMEOUT)" --poll-interval "$(POLL_INTERVAL)")
 
-.PHONY: build build-daemon build-viewer docker-build owl test verify ci ci-go ci-helm ci-binaries ci-client ci-visualize run serve status status-server list-entities-server get-entity-server list-relations-server neighbors-server expand-node-server collapse-node-graph observe-status diagnose-pod diagnose-workload diagnose-pod-server diagnose-workload-server visualize visualize-go visualize-check live-check verify-live require-kubeconfig require-entry
+.PHONY: build build-daemon build-viewer docker-build owl test verify ci ci-go ci-helm ci-binaries ci-client ci-visualize run serve status status-server list-entities-server get-entity-server list-relations-server neighbors-server expand-node-server collapse-node-graph observe-status diagnose-pod diagnose-workload diagnose-helm-release diagnose-pod-server diagnose-workload-server visualize visualize-go visualize-check live-check verify-live require-kubeconfig require-entry
 
 build:
 	mkdir -p bin
@@ -174,6 +174,15 @@ diagnose-workload: build require-kubeconfig require-entry
 	  --max-depth "$(MAX_DEPTH)" \
 	  --storage-max-depth "$(STORAGE_MAX_DEPTH)" $(make_diagnostic_budget_args)
 
+diagnose-helm-release: build require-kubeconfig require-entry
+	$(BINARY) \
+	  $(CLI_CONFIG_ARGS) \
+	  --diagnose-helm-release \
+	  --namespace "$(NAMESPACE)" \
+	  --name "$(NAME)" \
+	  --max-depth "$(MAX_DEPTH)" \
+	  --storage-max-depth "$(STORAGE_MAX_DEPTH)" $(make_diagnostic_budget_args)
+
 diagnose-pod-server: build require-entry
 	$(BINARY) \
 	  --server "$(SERVER_URL)" \

QUICKSTART.md

@@ -556,6 +556,22 @@ When resources carry standard Helm metadata, diagnostic graphs can also include
 `installs_chart` edges. These edges are label evidence with confidence scores,
 not exact Helm manifest membership.
 
+For a failed Helm upgrade where the user does not have CLI output, start from
+the release and inspect current cluster evidence:
+
+```bash
+kubernetes-ontology \
+  --server "http://127.0.0.1:18080" \
+  --diagnose-helm-release \
+  --namespace default \
+  --name my-release
+```
+
+The response can identify release-owned resources, rollout blockers, Events,
+and probable chart ownership. It cannot observe Helm template, values,
+repository, client, hook, or `--atomic` rollback errors unless the user provides
+the Helm output.
+
 Pod-centered diagnostic queries keep shared nodes bounded by default. For
 example, a pod's `ServiceAccount` is shown, but the traversal does not continue
 through that ServiceAccount to every other pod using it. Use

README.md

@@ -112,6 +112,32 @@ Resources labeled with standard Helm metadata produce `HelmRelease` and
 `installs_chart` edges with `label_evidence` provenance and confidence scores.
 These are ownership hints from labels, not exact manifest membership.
 
+### Helm Upgrade Failure Triage
+
+When a user only says "helm upgrade failed" and does not have the Helm CLI
+output, `kubernetes-ontology` can still diagnose the current cluster state for
+that release:
+
+```bash
+kubernetes-ontology \
+  --server "http://127.0.0.1:18080" \
+  --diagnose-helm-release \
+  --namespace default \
+  --name my-release
+```
+
+The response expands the probable release-owned resources and chart evidence.
+It also marks the missing Helm-side evidence explicitly:
+
+- `helm_cli_output_not_observed`: template, values, repository, client, hook,
+  and `--atomic` rollback errors are outside current Kubernetes object state.
+- `helm_manifest_evidence_not_collected`: default Helm ownership is label and
+  annotation evidence, not exact release manifest membership.
+
+For rollout failures that reached the cluster, follow the release graph into
+the affected Workload or Pod diagnostic. For render/client failures, ask the
+user to paste the `helm upgrade` stderr or `helm status/history` output.
+
 ## Agent Onboarding
 
 This repository provides a Codex-style skill:
@@ -390,6 +416,16 @@ Diagnose a pod:
   --max-edges 400
 ```
 
+Diagnose a Helm release after a failed upgrade:
+
+```bash
+./bin/kubernetes-ontology \
+  --server "http://127.0.0.1:18080" \
+  --diagnose-helm-release \
+  --namespace default \
+  --name my-release
+```
+
 Diagnostic responses include additive `partial`, `warnings`, `budgets`,
 `rankedEvidence`, `degradedSources`, and `conflicts` fields. Agents should use
 those fields to distinguish bounded evidence from complete cluster truth.

README.zh-CN.md

@@ -70,6 +70,21 @@ Helm 关系会以 `managed_by_helm_release` 和 `installs_chart` 边呈现，
 provenance 是 `label_evidence`，并带 confidence。它们是标签证据下的归属
 提示，不等同于精确 manifest 成员关系。
 
+如果用户说“helm upgrade 失败了”但没有 Helm CLI 输出，可以先从当前集群状态
+诊断 release：
+
+```bash
+kubernetes-ontology \
+  --server "http://127.0.0.1:18080" \
+  --diagnose-helm-release \
+  --namespace default \
+  --name my-release
+```
+
+返回结果会展示 release 可能管理的资源、chart 证据、rollout 阻塞点和事件。
+同时也会明确标记：template、values、repo/client、hook、`--atomic` rollback
+原始错误需要用户提供 Helm stderr/status/history 才能判断。
+
 运行时支持：
 
 - 启动时全量快照
@@ -313,6 +328,16 @@ OpenKruise，这是正常情况，不需要为此中断启动。
   --max-edges 400
 ```
 
+诊断 Helm release：
+
+```bash
+./bin/kubernetes-ontology \
+  --server "http://127.0.0.1:18080" \
+  --diagnose-helm-release \
+  --namespace default \
+  --name my-release
+```
+
 诊断返回会额外包含 `partial`、`warnings`、`budgets`、
 `rankedEvidence`、`degradedSources` 和 `conflicts`。Agent 应优先读取
 这些字段，区分“有边界的证据图”和“完整集群事实”。

cmd/kubernetes-ontology/main.go

@@ -49,6 +49,7 @@ func main() {
 	var statusOnly bool
 	var diagnosePod bool
 	var diagnoseWorkload bool
+	var diagnoseHelmRelease bool
 	var observeDuration time.Duration
 	var pollInterval time.Duration
 	var streamMode string
@@ -92,6 +93,7 @@ func main() {
 	flag.BoolVar(&statusOnly, "status", false, "Alias for --status-only")
 	flag.BoolVar(&diagnosePod, "diagnose-pod", false, "Diagnose a Pod by --namespace and --name")
 	flag.BoolVar(&diagnoseWorkload, "diagnose-workload", false, "Diagnose a Workload by --namespace and --name")
+	flag.BoolVar(&diagnoseHelmRelease, "diagnose-helm-release", false, "Diagnose a Helm release by --namespace and --name")
 	flag.DurationVar(&observeDuration, "observe-duration", 0, "Keep observing the cluster for this duration before printing status or query output")
 	flag.DurationVar(&pollInterval, "poll-interval", 10*time.Second, "Polling interval used with --observe-duration")
 	flag.StringVar(&streamMode, "stream-mode", string(collectk8s.StreamModePolling), "Continuous update stream mode for --observe-duration: informer or polling")
@@ -140,8 +142,14 @@ func main() {
 	if terminalKindsDisable {
 		expandTerminalNodes = true
 	}
-	if diagnosePod && diagnoseWorkload {
-		err := fmt.Errorf("only one of --diagnose-pod or --diagnose-workload may be set")
+	diagnoseModeCount := 0
+	for _, enabled := range []bool{diagnosePod, diagnoseWorkload, diagnoseHelmRelease} {
+		if enabled {
+			diagnoseModeCount++
+		}
+	}
+	if diagnoseModeCount > 1 {
+		err := fmt.Errorf("only one of --diagnose-pod, --diagnose-workload, or --diagnose-helm-release may be set")
 		if machineErrors {
 			writeMachineError(os.Stderr, err)
 		} else {
@@ -155,6 +163,9 @@ func main() {
 	if diagnoseWorkload {
 		entryKind = "Workload"
 	}
+	if diagnoseHelmRelease {
+		entryKind = "HelmRelease"
+	}
 
 	if collapseNode {
 		if err := collapseGraphFile(graphFile, entityID); err != nil {

docs/design/README.md

@@ -14,7 +14,9 @@ Recommended reading order:
 2. `current-state-and-next-steps.md` records the current implementation state.
 3. `open-source-mvp-plan.md` defines the open-source MVP boundary.
 4. `kubernetes-semantic-kernel-evolution.md` gives the long-term architecture.
-5. `continuous-runtime-technical-design.md` and
+5. `helm-upgrade-failure-user-story.md` standardizes the Helm upgrade failure
+   scenario where the user no longer has Helm CLI output.
+6. `continuous-runtime-technical-design.md` and
    `continuous-runtime-progress-snapshot.md` capture runtime design history.
 
 Detailed research notes are kept under `research/` so the design rationale and