Add faq, intro, deploy, secure and reverse proxy for TiDB Dashboard (#2737)

dashboard/dashboard-access.md

@@ -8,9 +8,11 @@ category: how-to
 
 To access TiDB Dashboard, visit <http://127.0.0.1:2379/dashboard> via your browser. Replace `127.0.0.1:2379` with the actual PD instance address and port.
 
+If multiple PD instances are deployed in your cluster and you can directly access **every** PD instance and port, you can simply replace `127.0.0.1:2379` in the <http://127.0.0.1:2379/dashboard/> address with **any** PD instance address and port.
+
 > **Note:**
 >
-> If you have deployed multiple PD components in your cluster, you can use the address of only one PD component to access TiDB Dashboard, because the Dashboard operates on only one PD component. If you access via other PD components, your browser is redirected to that PD component. Therefore, if the firewall is not configured for this instance on which PD operates, you might not be able to access TiDB Dashboard.
+> If a firewall or reverse proxy is configured and you cannot directly access every PD instance, you might not be able to access TiDB Dashboard. Usually, this is because the firewall or reverse proxy is not correctly configured. See [Use TiDB Dashboard behind Reverse Proxy](/dashboard/dashboard-ops-reverse-proxy.md) and [Secure TiDB Dashboard](/dashboard/dashboard-ops-security.md) to learn correctly configure the firewall or reverse proxy when multiple PD instances are deployed.
 
 ## Browser compatibility
 

dashboard/dashboard-faq.md

@@ -0,0 +1,60 @@
+---
+title: TiDB Dashboard FAQ
+summary: Learn about the frequently asked questions (FAQs) and answers about TiDB Dashboard.
+category: how-to
+---
+
+# TiDB Dashboard FAQ
+
+This document summarizes the frequently asked questions (FAQs) and answers about TiDB Dashboard.
+
+## Access-related FAQ
+
+### When the firewall or reverse proxy is configured, I am redirected to an internal address other than TiDB Dashboard
+
+When multiple Placement Driver (PD) instances are deployed in a cluster, only one of the PD instances actually runs the TiDB Dashboard service. If you access other PD instances instead of this one, your browser redirects you to another address. If the firewall or reverse proxy is not properly configured for accessing TiDB Dashboard, when you visit the Dashboard, you might be redirected to an internal address that is protected by the firewall or reverse proxy.
+
+- See [TiDB Dashboard Multi-PD Instance Deployment](/dashboard/dashboard-ops-deploy.md#) to learn the working principle of TiDB Dashboard with multiple PD instances.
+- See [Use TiDB Dashboard through a Reverse Proxy](/dashboard/dashboard-ops-reverse-proxy.md) to learn how to correctly configure a reverse proxy.
+- See [Improve TiDB Dashboard Security](/dashboard/dashboard-ops-security.md) to learn how to correctly configure the firewall.
+
+### When TiDB Dashboard is deployed with dual network interface cards (NICs), TiDB Dashboard cannot be accessed using another NIC
+
+For security reasons, TiDB Dashboard on PD only monitors the IP addresses specified during deployment (that is, it only listens on one NIC), not on `0.0.0.0`. Therefore, when multiple NICs are installed on the host, you cannot access TiDB Dashboard using another NIC.
+
+If you have deployed TiDB using the `tiup cluster` or `tiup playground` command, currently this problem cannot be solved. It is recommended that you use a reverse proxy to safely expose TiDB Dashboard to another NIC. For details, see [Use TiDB Dashboard through Reverse Proxy](/dashboard/dashboard-ops-reverse-proxy.md).
+
+## UI-related FAQ
+
+### A `prometheus_not_found` error is shown in **QPS** and **Latency** sections on the Overview page
+
+The **QPS** and **Latency** sections on the **Overview** page require a cluster with Prometheus deployed. Otherwise, the error is shown. You can solve this problem by deploying a Prometheus instance in the cluster.
+
+If you still encounter this problem when the Prometheus instance has been deployed, the possible reason is that your deployment tool is out of date (TiUP, TiDB Operator, or TiDB Ansible), and your tool does not automatically report metrics addresses, which makes TiDB Dashboard unable to query metrics. You can upgrade you deployment tool to the latest version and try again.
+
+If your deployment tool is TiUP, take the following steps to solve this problem. For other deployment tools, refer to the corresponding documents of those tools.
+
+1. Upgrade TiUP and TiUP Cluster:
+
+    {{< copyable "shell-regular" >}}
+
+    ```bash
+    tiup update --self
+    tiup update cluster --force
+    ```
+
+2. After the upgrade, when a new cluster is deployed with Prometheus instances, the metrics can be displayed normally.
+
+3. For an existing cluster, you can restart this cluster to report the metrics addresses. Replace `CLUSTER_NAME` with the actual cluster name:
+
+    {{< copyable "shell-regular" >}}
+
+    ```bash
+    tiup cluster start CLUSTER_NAME
+    ```
+
+   Even if the cluster has been started, still execute this command. This command does not affect the normal application in the cluster, but refreshes and reports the metrics addresses, so that the monitoring metrics can be displayed normally in TiDB Dashboard.
+
+### An `invalid connection` error is shown in **Top SQL Statements** and **Recent Slow Queries** on the Overview page
+
+The possible reason is that you have enabled the `prepared-plan-cache` feature of TiDB. As an experimental feature, when enabled, `prepared-plan-cache` might not function properly in specific TiDB versions, which could cause this problem in TiDB Dashboard (and other applications). You can disable `prepared-plan-cache` by updating [TiDB Configuration file](/tidb-configuration-file.md#prepared-plan-cache) to solve this problem.

dashboard/dashboard-intro.md

@@ -0,0 +1,63 @@
+---
+title: TiDB Dashboard Introduction
+summary: Introduce TiDB Dashboard.
+category: how-to
+---
+
+# TiDB Dashboard Introduction
+
+TiDB Dashboard is a Web UI for monitoring, diagnosing, and managing the TiDB cluster, which is available since v4.0. It is built into the PD component and does not require an independent deployment.
+
+![TiDB Dashboard interface](/media/dashboard/dashboard-intro.gif)
+
+TiDB Dashboard is open-sourced on [GitHub](https://github.com/pingcap-incubator/tidb-dashboard).
+
+This document introduces the main features of TiDB Dashboard. You can click links in the following sections to learn more details.
+
+## Show the overall running status of the TiDB cluster
+
+You can use TiDB Dashboard to learn the TiDB cluster's queries per second (QPS), execution time, the types of SQL statements that consume the most resources, and other overview information.
+
+See [TiDB Dashboard Overview](/dashboard/dashboard-overview.md) for details.
+
+## Show the running status of components and hosts
+
+You can use TiDB Dashboard to view the running status of TiDB, TiKV, PD, TiFlash components in the entire cluster and the running status of the host on which these components are located.
+
+See [TiDB Dashboard Cluster Information Page](/dashboard/dashboard-cluster-info.md) for details.
+
+## Show distribution and trends of read and write traffic
+
+The Key Visualizer feature of TiDB Dashboard visually shows the change of read and write traffic over time in the entire cluster in the form of heatmap. You can use this feature to timely discover changes of application modes or locate hotspot issues with uneven performance.
+
+See [Key Visualizer Page](/dashboard/dashboard-key-visualizer.md) for details.
+
+## Show a list of execution information of all SQL statements
+
+The execution information of all SQL statements is listed on the SQL Statements page. You can use this page to learn the execution time and total executions at all stages, which helps you analyze and locate the SQL queries that consume the most resources and improve the overall cluster performance.
+
+See [SQL Statements Page of TiDB Dashboard](/dashboard/dashboard-statement-list.md) for details.
+
+## Learn the detailed execution information of slow queries
+
+The Slow Queries page of TiDB Dashboard shows a list of all SQL statements that take a long time to execute, including the SQL texts and execution information. This page helps you locate the cause of slow queries or performance jitter.
+
+See [Slow Queries Page](/dashboard/dashboard-slow-query.md) for details.
+
+## Diagnose common cluster problems and generate reports
+
+The diagnostic feature of TiDB Dashboard automatically determines whether some common risks (such as inconsistent configurations) or problems exist in the cluster, generates reports, and gives operation suggestions, or compares the status of each cluster metric in different time ranges for you to analyze possible problems.
+
+See [TiDB Dashboard Cluster Diagnostics Page](/dashboard/dashboard-diagnostics-access.md) for details.
+
+## Query logs of all components
+
+On the Search Logs page of TiDB Dashboard, you can quickly search logs of all running instances in the cluster by keywords, time range, and other conditions, package these logs, and download them to your local machine.
+
+See [Search Logs Page](/dashboard/dashboard-log-search.md) for details.
+
+## Collect profiling data for each instance
+
+This is an advanced debugging feature that lets you profile each instance online and analyze various internal operations an instance performed during the profiling data collection period and the proportion of the operation execution time in this period without third-party tools.
+
+See [Profile Instances Page](/dashboard/dashboard-profiling.md) for details.

dashboard/dashboard-ops-deploy.md

@@ -0,0 +1,139 @@
+---
+title: Deploy TiDB Dashboard
+summary: Learn how to deploy TiDB Dashboard.
+category: how-to
+---
+
+# Deploy TiDB Dashboard
+
+The TiDB Dashboard UI is built into the PD component for v4.0 or higher versions, and no additional deployment is required. Simply deploy a standard TiDB cluster, and TiDB Dashboard will be there.
+
+See the following documents to learn how to deploy a standard TiDB cluster:
+
++ [Quick Start Guide for the TiDB Database Platform](/quick-start-with-tidb.md#deploy-a-local-test-environment-using-tiup-playground)
++ [Deploy TiDB in Production Environment](/production-deployment-using-tiup.md)
++ [Kubernetes environment deployment](https://pingcap.com/docs/tidb-in-kubernetes/stable/access-dashboard/)
+
+> **Note:**
+>
+> You cannot deploy TiDB Dashboard in a TiDB cluster earlier than v4.0.
+
+## Deployment with multiple PD instances
+
+When multiple PD instances are deployed in the cluster, only one of these instances serves the TiDB Dashboard.
+
+When PD instances are running for the first time, they automatically negotiate with each other to choose one instance to serve the TiDB Dashboard. TiDB Dashboard will not run on other PD instances. The TiDB Dashboard service will always be provided by the chosen PD instance no matter PD instances are restarted or new PD instances are joined. However, there will be a re-negotiation when the PD instance that serves TiDB Dashboard is removed from the cluster (scaled-in). The negotiation process does not need user intervention.
+
+When you access a PD instance that does not serve TiDB Dashboard, the browser will be redirected automatically to guide you to access the PD instance that serves the TiDB Dashboard, so that you can access the service normally. This process is illustrated in the image below.
+
+![Process Schematic](/media/dashboard/dashboard-ops-multiple-pd.png)
+
+> **Note:**
+>
+> The PD instance that serves TiDB Dashboard might not be a PD leader.
+
+### Check the PD instance that actually serves TiDB Dashboard
+
+For a running cluster deployed using TiUP, you can use the `tiup cluster display` command to see which PD instance serves TiDB Dashboard. Replace `CLUSTER_NAME` with the cluster name.
+
+{{< copyable "shell-regular" >}}
+
+```bash
+tiup cluster display CLUSTER_NAME --dashboard
+```
+
+A sample output is as follows:
+
+```bash
+http://192.168.0.123:2379/dashboard/
+```
+
+> **Note:**
+>
+> This feature is available only in the later version of the `tiup cluster` deployment tool (v1.0.3 or later). You can upgrade `tiup cluster` with the following commands:
+>
+> {{< copyable "shell-regular" >}}
+>
+> ```bash
+> tiup update --self
+> tiup update cluster --force
+> ```
+
+### Switch to another PD instance to serve TiDB Dashboard
+
+For a running cluster deployed using TiUP, you can use the `tiup ctl pd` command to change the PD instance that serves TiDB Dashboard, or re-specify a PD instance to serve TiDB Dashboard when it is disabled:
+
+{{< copyable "shell-regular" >}}
+
+```bash
+tiup ctl pd -u http://127.0.0.1:2379 config set dashboard-address http://9.9.9.9:2379
+```
+
+In the command above:
+
+- Replace `127.0.0.1:2379` with the IP and port of any PD instance.
+- Replace `9.9.9.9:2379` with the IP and port of the new PD instance that you desire to run the TiDB Dashboard service.
+
+You can use the `tiup cluster display` command to see whether the modification is taking effect (replace `CLUSTER_NAME` with the cluster name):
+
+{{< copyable "shell-regular" >}}
+
+```bash
+tiup cluster display CLUSTER_NAME --dashboard
+```
+
+> **Warning:**
+>
+> If you change the instance to run TiDB Dashboard, the local data stored in the previous TiDB Dashboard instance will be lost, including the Key Visualize history and search history.
+
+## Disable TiDB Dashboard
+
+For a running cluster deployed using TiUP, use the `tiup ctl pd` command to disable TiDB Dashboard on all PD instances (replace `127.0.0.1:2379` with the IP and port of any PD instance):
+
+{{< copyable "shell-regular" >}}
+
+```bash
+tiup ctl pd -u http://127.0.0.1:2379 config set dashboard-address none
+```
+
+After disabling TiDB Dashboard, checking which PD instance provides the TiDB Dashboard service will fail:
+
+```
+Error: TiDB Dashboard is disabled
+```
+
+Visiting the TiDB Dashboard address of any PD instance via the browser will also fail:
+
+```
+Dashboard is not started.
+```
+
+## Re-enable TiDB Dashboard
+
+For a running cluster deployed using TiUP, use the `tiup ctl pd` command to request PD to renegotiate an instance to run TiDB Dashboard (replace `127.0.0.1:2379` with the IP and port of any PD instance):
+
+{{< copyable "shell-regular" >}}
+
+```bash
+tiup ctl pd -u http://127.0.0.1:2379 config set dashboard-address auto
+```
+
+After executing the command above, you can use the `tiup cluster display` command to view the TiDB Dashboard instance address automatically negotiated by PD (replace `CLUSTER_NAME` with the cluster name):
+
+{{< copyable "shell-regular" >}}
+
+```bash
+tiup cluster display CLUSTER_NAME --dashboard
+```
+
+You can also re-enable TiDB Dashboard by manually specifying the PD instance that serves TiDB Dashboard. See [Switch to another PD instance to serve TiDB Dashboard](#switch-to-another-pd-instance-to-serve-tidb-dashboard).
+
+> **Warning:**
+>
+> If the newly enabled TiDB Dashboard instance is different with the previous instance that served the TiDB Dashboard, the local data stored in the previous TiDB Dashboard instance will be lost, including Key Visualize history and search history.
+
+## What's next
+
+- To learn how to access and log into the TiDB Dashboard UI, see [Access TiDB Dashboard](/dashboard/dashboard-access.md).
+
+- To learn how to enhance the security of TiDB Dashboard, such as configuring a firewall, see [Improve TiDB Dashboard Security](/dashboard/dashboard-ops-security.md).