From 49a4b36f8be422097c75ca0de09048585661497d Mon Sep 17 00:00:00 2001
From: clyi <clyi@alauda.io>
Date: Fri, 15 May 2026 14:26:48 +0800
Subject: [PATCH] docs: add MetalLB monitoring guidance

---
 .../functions/configure_metallb.mdx           | 74 +++++++++++++++++++
 1 file changed, 74 insertions(+)

diff --git a/docs/en/configure/networking/functions/configure_metallb.mdx b/docs/en/configure/networking/functions/configure_metallb.mdx
index a374c4d52..a18f44561 100644
--- a/docs/en/configure/networking/functions/configure_metallb.mdx
+++ b/docs/en/configure/networking/functions/configure_metallb.mdx
@@ -50,6 +50,9 @@ Please ensure that you have read the [Installation](../../../networking/operator
 
 5. Click **Create**.
 
+> Note:
+> When you use BGP mode, allow TCP port 179 between each BGP peer and the MetalLB speaker nodes. If you configure a custom peer port, allow the configured port instead.
+
 ## Configure an External IP Address Pool with L2Advertisement or BGPAdvertisement by using the CLI
 
 ```yaml
@@ -114,6 +117,77 @@ spec:
 kubectl apply -f ippool-with-L2advertisement.yaml -f ippool-with-bgpadvertisement.yaml
 ```
 
+## Monitor MetalLB
+
+After you configure MetalLB, you can use the built-in dashboard and monitoring metrics to observe IP address allocation and BGP session status.
+
+> Note:
+> The built-in MetalLB dashboard is available in ACP 4.4.
+
+### View the built-in MetalLB dashboard
+
+1. Go to **Operations Center**.
+
+2. In the left navigation bar, click **Monitoring** > **Monitoring Dashboards**.
+
+3. Search for **MetalLB**, and then open the dashboard.
+
+The built-in MetalLB dashboard includes the following panels:
+
+| Panel | Description |
+| --- | --- |
+| **Exposed Services** | The number of LoadBalancer Services currently announced by MetalLB. |
+| **Available IPs** | The number of IP addresses still available across all address pools. |
+| **Established BGP Sessions** | The number of BGP sessions that are currently established. |
+| **Advertised Prefixes** | The number of BGP prefixes currently advertised by MetalLB. |
+| **Pool Usage Trend** | The IP address usage trend for selected address pools. |
+| **Selected Pool Capacity** | The used and available IP address capacity for selected address pools. |
+
+### Access the MetalLB metrics endpoint
+
+MetalLB exposes controller and speaker metrics through monitor Services in the `metallb-system` namespace. You can access these metrics from inside the cluster to confirm whether the components expose metrics correctly.
+
+Check the MetalLB monitor Services:
+
+```bash
+kubectl get svc -n metallb-system | grep monitor
+```
+
+Check the Service endpoints:
+
+```bash
+kubectl get endpointslice -n metallb-system -l kubernetes.io/service-name=controller-monitor-service
+kubectl get endpointslice -n metallb-system -l kubernetes.io/service-name=speaker-monitor-service
+```
+
+The endpoint addresses use port `17472` by default.
+
+Query the controller metrics endpoint from inside the cluster:
+
+```bash
+curl -s http://<controller-endpoint-address>:17472/metrics | grep '^metallb_'
+```
+
+Query a speaker metrics endpoint from inside the cluster:
+
+```bash
+curl -s http://<speaker-endpoint-address>:17472/metrics | grep '^metallb_'
+```
+
+If the command returns MetalLB metrics, the component metrics endpoint is available.
+
+### MetalLB metrics reference
+
+The built-in MetalLB dashboard uses the following metrics:
+
+| Metric | Source component | Description | Usage scenario |
+| --- | --- | --- | --- |
+| `metallb_speaker_announced` | Speaker | Indicates whether a LoadBalancer Service is announced from a speaker node. | Check which nodes announce LoadBalancer Services. |
+| `metallb_allocator_addresses_total` | Controller | Total number of IP addresses in address pools. | Calculate total pool capacity and available IPs. |
+| `metallb_allocator_addresses_in_use_total` | Controller | Number of IP addresses already allocated from address pools. | Calculate used IPs and pool usage trend. |
+| `metallb_bgp_session_up` | Speaker / BGP exporter | Indicates whether BGP sessions are established. | Check BGP session health. |
+| `metallb_bgp_announced_prefixes_total` | Speaker / BGP exporter | Number of BGP prefixes announced by MetalLB. | Check route advertisement status. |
+
 ## Troubleshooting MetalLB
 
 | Symptom                 | Possible Cause                               | Resolution                                    |