UNCLASSIFIED - NO CUI

Update Troubleshooting/Installation Page

General MR

Summary

Rewrote the Installation troubleshooting page since the old version was organized by generic categories instead of the order you'd actually hit a failure, which made it hard to find the right section mid-incident.

What I changed and why:

  • Restructured the page around the actual troubleshooting flow — diagnose → identify where reconciliation failed → check common failure points → reconcile → recover — instead of the old "Quick Diagnostics / Installation-Specific Issues / Recovery Steps" grouping. Easier to follow when you're actually mid-incident.
  • Added a symptom-to-check table so you can jump straight from what you're seeing (e.g. dependency ... is not ready, pods stuck Pending) to the right check, instead of reading through every section.
  • Removed (flux diff helmrelease)
  • Removed the hardcoded cert-manager|istio dependency check — Replaced with guidance to follow whatever dependency Flux actually reports.
  • Updated the Full Reset section
  • Added a Mermaid flowchart at the top showing the decision path (which resource fails first → which check to run), styled to match the color scheme already used on the Renovate and Troubleshooting Overview pages.
  • Linked out to Flux's own docs instead of restating things like reconcile command flags — that's Flux's behavior to maintain, not ours, so if it changes we're not stuck with a stale page.

Relevant logs/screenshots

(Include any relevant logs/screenshots)

Linked Issue

#3453 (closed)

Upgrade Notices

(Include any relevant notes about upgrades here or write "N/A" if there are none)

Merge request reports

Loading
Loading