run_c4145c7c4220b096

input

{
  "request": "Triage Jira ticket MZCLD-3834: Improve ArgoCD documentation for engineers",
  "references": [
    "https://mozilla-hub.atlassian.net/browse/MZCLD-3834"
  ],
  "sourceContext": {
    "issue": "MZCLD-3834"
  }
}

summary

MZCLD-3834 is a well-scoped Backlog epic (0 comments) proposing to improve ArgoCD documentation for Cloud Engineering on-call. It clearly articulates the problem (everyone now carries the ArgoCD pager but there's no runbook, no architecture doc, and no runbook_url on any of the 6 ArgoCD alert rules), defines four child tickets to scope out the work, states a documentation-location strategy (repo READMEs for structure, Confluence for narrative, dashboard blurbs linking out), and explicitly calls out what's out of scope (dashboard/alert fixes belong to MZCLD-3140). No Confluence page IDs/URLs were embedded in the extracted ticket text (only page names like "ArgoCD Admin Guide," "ArgoCD dashboard," and Wil's personal-space page), so those could not be independently pulled for verification via confluence.page.read. The ticket appears ready to move out of Backlog into planning/breakdown rather than needing clarification.

findings

• none

proposed actions

Triage note: This epic is well-scoped and ready to move forward. Suggest: (1) formally create/link the four child tickets mentioned in Scope (architecture/deployment doc, component-to-dashboard mapping, incident runbook + wiring into the 6 alert rules, and argo/ folder READMEs in global-platform-admin) so progress can be tracked independently; (2) prioritize the runbook + alert-wiring child ticket given 4 of 6 ArgoCD alerts are severity:high and currently carry no runbook_url, which is the most acute on-call gap; (3) confirm with the MZCLD-1281 owner whether the README-mirroring work should land before or in parallel with the argo/ README task, to avoid rework; (4) confirm the known dashboard defects (Panel 126 metric/threshold mismatch, Wil's unmerged state-timeline redesign, missing coverage for notifications-controller/dex/image-updater/ephemeral-access/rollouts) are tracked under MZCLD-3140 so they aren't lost given this epic intentionally treats them as out of scope. Recommend moving status from Backlog to Ready/To Do once child tickets are filed.

tool calls

[
  {
    "capability": "jira.issue.read",
    "args": {
      "key": "MZCLD-3834"
    },
    "result": {
      "key": "MZCLD-3834",
      "summary": "Improve ArgoCD documentation for engineers",
      "status": "Backlog",
      "description_text": "Background Everyone in Cloud Engineering now carries the pager for ArgoCD, but the documentation does not support that. The only admin-facing page is the  ArgoCD Admin Guide , and its \"Service requirements, monitoring, and on-call rotation\" section amounts to \"we address outages on a best-effort basis\". There is no runbook, no explanation of how the pieces fit together, and no guide to the  ArgoCD dashboard . At 1:30 AM that gap is the difference between triaging and guessing. ArgoCD is also shaped differently from a typical MozCloud workload: it deploys itself through its own Helm chart, and the chart emits Go-template placeholders that the ApplicationSet controller evaluates later against its own generators. Someone reading  argo/k8s/argocd-bootstrap  for the first time during an incident has no way to know that. Three concrete gaps: How ArgoCD is deployed is undocumented.  Nothing explains the permission domains, the self-managing bootstrap chart and its app-of-apps, the tenant to ApplicationSet to Application path, the two-stage templating, or the Terraform that fronts it. The dashboard is unreadable without prior knowledge.  It is organized by component (Controller Stats, AppSet Controller Telemetry, Repo Server Stats, Server Stats, Redis Stats), but nothing anywhere says what those components do or what users see when each one fails. The alerts have no runbooks.  The  MozCloud / ArgoCD Alerting  group has six rules, four of them  severity: high , and not one carries a  runbook / runbook_url  annotation. Whoever gets paged gets a summary line and nothing else. Goal Any Cloud Engineering engineer, including one who has never touched ArgoCD, can be paged for it and work the problem from the alert: understand what fired, find the component involved, read its logs, and know what \"normal\" looks like. Scope Four child tickets: Document the ArgoCD architecture and deployment model in the Admin Guide. Document what each ArgoCD component does and map it to the Grafana dashboard. Write the ArgoCD incident runbook, then wire it into the six alerts. Add READMEs documenting the  argo/  folder structure in  global-platform-admin . Where documentation lives To avoid maintaining the same thing twice: Repo structure lives in the repo.  The  argo/  READMEs are the source of truth for what each directory and chart is, since that detail changes with the code and should be reviewed alongside it. Narrative lives in Confluence.  The Admin Guide explains how ArgoCD works and how the pieces relate, at a level that does not need editing every time a template moves, and links to GitHub for the specifics. Each component gets one canonical description.  The dashboard carries short blurbs that link out, rather than becoming a third place we have to keep current. Related:  MZCLD-1281  is researching mirroring GitHub READMEs into Confluence, which would make the split above cheaper to maintain. Out of scope Fixing the dashboard and alerts themselves belongs with  MZCLD-3140  (improve alerts CloudEng get paged and alerted for), not here. Known items to carry over there: Panel 126 \"Service Availability\" uses  https_backend_request_count  while the 5XX alert uses  https_request_count ; the panel's thresholds are also inverted, so 100% renders yellow and 40% renders green. Wil's analysis and state-timeline redesign ( page ) has not been adopted into the shared dashboard and currently lives in a personal space. No dashboard coverage exists for the notifications controller, dex, image-updater, ephemeral-access, or rollouts, all of which we deploy. This epic documents what exists today, including the known-noise caveats, so the runbook is honest about the signals rather than blocking on fixing them.",
      "comment_count": 0,
      "comments": []
    }
  }
]

log