Fleet Geolocation Map in hub Alert Management Overview page

[sradco]

Summary

This proposal introduces a geographic map visualization for managed clusters on the hub alerting overview page. Clusters are plotted on a world map as dots — colored by health status and sized by configurable metrics — providing spatial awareness of fleet health.

Key Design Decisions

• Single label: One geolocation label on ManagedCluster (country/state codes, e.g., IE, US.VA)
• Panel-side resolution: The Perses geomap panel resolves location codes to coordinates using a built-in gazetteer (countries + states). No server-side coordinate resolution or additional hub resources needed.
• Existing metric: Leverages the existing acm_managed_cluster_labels metric — no new synthetic metrics.
• Co-located clusters: Individual dots per cluster with deterministic offset for same-location clusters, preserving per-cluster size/color for prioritization.
• Offline-capable: Bundled PMTiles basemap (~50MB) — works in air-gapped environments.

Phased Delivery

1. Phase 1 (Data Model): Add geolocation to the label allowlist, document conventions, file upstream Perses issue.
2. Phase 2 (Visualization + UI): Integrate Perses geomap panel, add ACM Console location picker.
3. Phase 3 (Auto-derivation): Controller translates cloud topology labels to country/state codes.

Dependencies

• Upstream Perses geomap panel: [Feature] Plugin Request: Geomap Panel perses/perses#4132

Test Plan

Covered in the enhancement document.

Made with Cursor

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign moadz 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:

• enhancements/monitoring/OWNERS

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

[sradco]

@jgbernalp @saswatamcode Please review this enhancement.

[saswatamcode]

To be quite honest here, I don't really see a strict need for this? Explained more in comments below

[saswatamcode]

You can set this to auto right?

[sradco]

What do you mean?
It doesnt replace the original label, it adds a new one if missing, that is derived from the topology.kubernetes.io/region label

[saswatamcode]

I, of course, agree with the utility of knowing what region and AZ an alert is firing in, but I don't understand why we have to visualize this in a map.

Usually, admin/SRE personas don't exactly care about seeing alerts on a map, as there is virtually no utility in having that spatial context.

I think what might be useful is grouping together alerts by regions and AZs, which will give an SRE the same info, without a complex map view.

However, doing that automatically from our side is something I would caution against for a couple of reasons,

• Region/AZs from a cloud provider are something we can be aware of, but if a customer is running their own on-prem infra, we aren't really aware of what their region/AZ split looks like.
• Most admins/SRE teams label or name their infra (and alerts as well) by their associated geographic position, as best practice or as per internal conventions. This is on purpose, so that their teams can determine regionality/az at a glance. We would have to actively override that on resources, especially alerts, which will likely cause customers quite a lot of confusion

[sradco]

Thanks for the feedback @saswatamcode .
A few clarifications:

• Map vs. grouping: You're right that for daily SRE triage, a grouped list by region is more practical. The map isn't replacing that — it's a complementary view mode (toggle) for scenarios where spatial context helps: large edge fleets (50–500+ sites), blast radius assessment, and stakeholder/NOC communication. I'll make this framing clearer in the proposal and add "grouped by region" to Alternatives Considered.

• On overriding labels: To clarify — this doesn't modify any existing resources or alert labels. geolocation is a new, opt-in label on ManagedCluster resources. Clusters without it simply don't appear on the map. Existing conventions are untouched.

• On on-prem: Agreed, we can't auto-derive for on-prem. The design is entirely opt-in — on-prem customers who want it set the label themselves; those who don't aren't affected.

• On scope: The core deliverable is the geolocation label convention, which enables grouping/filtering independently of the map. The map panel is Phase 2, gated on upstream Perses availability.

[openshift-ci]

@sradco: all tests passed!

Full PR test history. Your PR dashboard.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.