Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

diagnose state reconcile: rebuild state.yaml from the live cluster

Open
  • Is something wrong?
#1,237 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
go, kubernetes
Domain
infrastructure

Research direction

Start in internal/reality beside the persisted-keyed RefreshState, then read #1187 for consensus managed-state readback, #1225 for drift, and #1233 for overwrite policy. The issue also names the diagnostics framework (#1111) and per-component checks (#1114) as dependencies. Done means read-only reconcile reports stale, orphaned, and drifted entries, while gated --fix rebuilds state from discoverable live fields, reports unreconstructable fields, and passes the stated acceptance checks.

Written by the indexing model from the issue text.

Description

Part of the diagnostics epic (#1110). Depends on the diagnostics framework (#1111) and the per-component checks (#1114).

The recovery path for a state.yaml that is missing, corrupt, or diverged from the live cluster. This is the one mutating command in the diagnostics surface — everything else is read-only.

Why

Today there is no way to rebuild state.yaml from reality:

  • consensusChecker.RefreshState iterates the persisted ConsensusNodes map and keys each lookup off the persisted identity (OrbitName/NodeId/Namespace). With state missing or an entry absent, it returns nothing — it enriches known entries, it does not discover them.
  • consensus node install guards on the live capsule and blocks (PrecheckConsensusNotInstalled, unless --force), and the post-run flush then writes an incomplete state — so "delete state and re-install" makes things worse, not better.

A hand-edit of state.yaml is the only recovery today. This command replaces that.

Scope

  • Cluster discovery (new reality capability): list the live managed resources for a component (e.g. every ConsensusCapsule + its Orbit) without relying on persisted identity, and reconstruct the corresponding state entries from the live CRs (identity + the live-readable fields the checker already knows how to read).
  • Reconcile report (read-only): show the three-way divergence — entries in state but not in the cluster (stale), entries in the cluster but not in state (orphans — today's exact failure), and entries present on both with field drift (via internal/drift producers).
  • Repair (mutating): diagnose state reconcile [--fix] (or diagnose state --fix) rewrites state.yaml from the reconstructed live view. Gated by the block-unless-override policy (#1233): interactive runs require an explicit override before overwriting; the daemon reconciles but records what it overwrote (audit trail). Writes go through the normal atomic write + hashing.
solo-provisioner diagnose state reconcile [--component <c>] [--namespace <ns>]   # report divergence (read-only)
solo-provisioner diagnose state reconcile --fix [--force]                        # rebuild state.yaml from the cluster (gated)

Acceptance

  • On a host with a deployed consensus node but no state.yaml, the read-only reconcile lists the node as an orphan (in cluster, not in state) with an actionable hint.
  • --fix reconstructs a valid state.yaml (identity + live-readable fields) from the live cluster; a subsequent consensus node diagnose reports no divergence.
  • Interactive --fix that would overwrite diverged state blocks without an override and proceeds with it (#1233); the daemon path proceeds and logs the overwrite.
  • Fields the live cluster cannot report (e.g. ManagedSpec where it is not fully readable back) are reported as un-reconstructable rather than silently guessed.

Notes

  • Builds on #1187 (consensus managed-state readback) and #1225 (drift). Discovery is the inverse of the persisted-keyed RefreshState and belongs beside it in internal/reality.
  • Supersedes the epic's "doctor --fix tracked separately" note for the state-reconstruction case; health-remediation --fix remains a separate future.
Dominant language
Go
Stars
3
Forks
1
Avg merge
3d 17h
Merged PRs (30d)
16

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from hashgraph/solo-weaver

All issues in hashgraph/solo-weaver

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.