feat(hcpctl): add velero backup queries to snapshot gatherer

[Tim Steffens (tmstff)]

⚠ Unverified ⚠

• Completely AI generated, nothing verified so far. Can be taken as basis, but the actual effort (verification) is still missing.

Why

hcpctl snapshot gathers cluster-state snapshots for offline analysis, but has no visibility into Velero backup health. When a backup fails, there is currently no snapshot signal to reason over — SREs must correlate Velero state by hand.

This PR wires the Velero backup signals into the snapshot gatherer as groundwork so the data can subsequently be surfaced to hcpctl snapshot analyze.

Tracked by ARO-29442 (child of Epic ARO-22221 — Backup Operations & Monitoring). This is the deferred "snapshot" step split out of the must-gather work in ARO-28989 / #6791.

What

• Adds six Velero query specs under pkg/snapshot/queries/velero: backups, schedules, dataUploads, deleteBackupRequests, logs, serverLogs, plus a mgmtCluster helper query.
• Seeds the management-cluster name(s) in the gatherer so the queries scope correctly.
• Registers the queries in the snapshot query set, with tests.

Design notes

Mirrors the must-gather Velero query design from #6791:

• serverLogs is cross-HCP by design — the velero server and node-agent are shared per management cluster, so a shared-plane failure has no per-HCP token.
• The HCP-scoped queries pin to the HCP via Backup-CR namespace / resource tokens.

Scope

Independent of #6791 — touches only pkg/snapshot (untouched by that PR), so this is based directly on main.

Follow-up

Consuming this data in hcpctl snapshot analyze (prompt/render + correlation) is the remaining part of ARO-29442.

🤖 Generated with Claude Code

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: tmstff
Once this PR has been reviewed and has the lgtm label, please assign janboll for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• tooling/hcpctl/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[Copilot]

🟡 Changes recommended

The new Velero log/CR queries use Kusto has/has_any with hyphenated namespace tokens, which can produce incorrect (over-broad) matches and should be corrected before merge.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR extends hcpctl snapshot’s Kusto-backed snapshot gatherer to collect Velero backup health signals (CR history + aggregated component/server logs), so offline snapshot analysis can reason about backup failures without manual cross-correlation.

Changes:

• Adds a Velero query suite under pkg/snapshot/queries/velero (Backups/Schedules/DataUploads/DeleteBackupRequests + logs + serverLogs) plus a mgmtCluster discovery query to scope server logs to the right management cluster(s).
• Wires management-cluster name seeding into the gatherer and registers the new queries into the snapshot query chain.
• Adds unit tests to ensure templates render, Velero query readiness gating is correct, and mgmt-cluster discovery results are stored.

File summaries

File	Description
tooling/hcpctl/pkg/snapshot/queries/velero/serverLogs/README.md	Documents the shared (cross-HCP) Velero server log query semantics and triage guidance.
tooling/hcpctl/pkg/snapshot/queries/velero/serverLogs/query.kql	Adds KQL to aggregate Velero server warning/error logs, scoped by discovered management cluster list.
tooling/hcpctl/pkg/snapshot/queries/velero/schedules/README.md	Documents Schedule CR snapshot intent and triage guidance.
tooling/hcpctl/pkg/snapshot/queries/velero/schedules/query.kql	Adds KQL to snapshot Schedule CR state over time for the target HCP.
tooling/hcpctl/pkg/snapshot/queries/velero/mgmtCluster/README.md	Documents management-cluster discovery used to scope serverLogs.
tooling/hcpctl/pkg/snapshot/queries/velero/mgmtCluster/query.kql	Adds KQL to discover management cluster(s) from Velero Backup CR snapshots.
tooling/hcpctl/pkg/snapshot/queries/velero/logs/README.md	Documents aggregated per-HCP Velero component logs query.
tooling/hcpctl/pkg/snapshot/queries/velero/logs/query.kql	Adds KQL to aggregate Velero component logs associated with the HCP’s namespaces.
tooling/hcpctl/pkg/snapshot/queries/velero/deleteBackupRequests/README.md	Documents DeleteBackupRequest CR snapshots and how to correlate them.
tooling/hcpctl/pkg/snapshot/queries/velero/deleteBackupRequests/query.kql	Adds KQL to snapshot DeleteBackupRequest CR state for the HCP.
tooling/hcpctl/pkg/snapshot/queries/velero/dataUploads/README.md	Documents DataUpload CR snapshot intent and failure triage hints.
tooling/hcpctl/pkg/snapshot/queries/velero/dataUploads/query.kql	Adds KQL to snapshot DataUpload CR state over time for the HCP.
tooling/hcpctl/pkg/snapshot/queries/velero/backups/README.md	Documents Backup CR snapshot intent and triage guidance.
tooling/hcpctl/pkg/snapshot/queries/velero/backups/query.kql	Adds KQL to snapshot Backup CR phase transitions and failure metadata over time.
tooling/hcpctl/pkg/snapshot/queries.go	Introduces ManagementClusterNames, adds Velero query specs (including mgmtCluster discovery) to the query chain.
tooling/hcpctl/pkg/snapshot/queries_test.go	Adds unit tests for template rendering, readiness gating, IN-list rendering, and discovery result handling.
tooling/hcpctl/pkg/snapshot/gatherer.go	Seeds ManagementClusterNames from the PR-job hint to scope serverLogs.

Review details

• Files reviewed: 17/17 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.