tiup: document Prometheus external labels

[zanmato1984]

First-time contributors' checklist

• I've signed the Contributor License Agreement, which is required for the repository owners to accept my contribution.

What is changed, added or deleted? (Required)

This PR documents TiUP support for monitoring_servers[].external_labels.

It updates the TiUP cluster and DM topology references to describe the new field, its validation rules, and a minimal example. It also adds a dedicated section to the monitoring customization guide to explain how TiUP renders external_labels during deploy, scale-out, scale-in, and reload.

The compatibility note is explicit: older TiUP versions do not ignore this unknown field. They fail to parse the topology file.

Which TiDB version(s) do your changes apply to? (Required)

• master (the latest development version)
• v9.0 (TiDB 9.0 versions)
• v8.5 (TiDB 8.5 versions)
• v8.1 (TiDB 8.1 versions)
• v7.5 (TiDB 7.5 versions)
• v7.1 (TiDB 7.1 versions)
• v6.5 (TiDB 6.5 versions)

What is the related PR or file link(s)?

• This PR is translated from:
• Other reference link(s):
  • Support modify external_labels in prometheus.yml for Prometheus tiup#1795
  • cluster: support Prometheus external labels in topology tiup#2719

AI agent involvement

• The changes in this PR were primarily made by an AI agent on behalf of the PR author.

Do your changes match any of the following descriptions?

• Delete files
• Change aliases
• Need modification after applied to another branch
• Might cause conflicts after applied to another branch

Summary by CodeRabbit

• New Features
  • Added documentation for configuring Prometheus global external labels through TiUP topology settings.
  • Included configuration examples and guidance for label naming and reserved labels.
  • Documented support beginning with TiUP v1.17.0, including deployment, scaling, and reload behavior.
• Documentation
  • Clarified that unsupported TiUP versions reject configurations containing this field during topology parsing.

[ti-chi-bot]

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: fc14c230-8161-47af-a00e-eb4351787d3c

📥 Commits

Reviewing files that changed from the base of the PR and between 34b4d4a and 83783e9.

📒 Files selected for processing (3)

• tiup/customized-montior-in-tiup-environment.md
• tiup/tiup-cluster-topology-reference.md
• tiup/tiup-dm-topology-reference.md

---

📝 Walkthrough

Walkthrough

Documents the TiUP monitoring_servers.external_labels topology field, sample configurations, Prometheus label restrictions, TiUP version support, and parsing behavior across cluster, DM, and customization references.

Changes

TiUP external labels documentation

Layer / File(s)	Summary
Topology reference field and examples tiup/tiup-cluster-topology-reference.md, tiup/tiup-dm-topology-reference.md	Adds monitoring_servers.external_labels descriptions and example values for cluster and DM topology configurations.
Prometheus customization guidance tiup/customized-montior-in-tiup-environment.md	Documents configuring Prometheus global external labels, label restrictions, TiUP version support, and behavior during deployment, scaling, and reload operations.

Estimated code review effort: 1 (Trivial) | ~3 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly states the main documentation change about Prometheus external labels in TiUP.
Description check	✅ Passed	The description matches the template and covers the change, affected versions, related links, AI involvement, and other required checkboxes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[ti-chi-bot]

[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 ask for approval from lilin90. For more information see the Code Review Process.
Please ensure that each of them provides their approval before proceeding.

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

Details

Needs approval from an approver in each of these files:

• OWNERS

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

[ti-chi-bot]

[LGTM Timeline notifier]

Timeline:

• 2026-07-27 03:54:43.220426334 +0000 UTC m=+1809069.256521390: ☑️ agreed by lilin90.