Use TiDB Dashboard behind a Reverse Proxy

Use TiDB Dashboard behind a Reverse Proxy

You can use a reverse proxy to safely expose the TiDB Dashboard service from the internal network to the external.

Procedures

Step 1: Get the actual TiDB Dashboard address

When multiple PD instances are deployed in the cluster, only one of the PD instances actually runs TiDB Dashboard. Therefore, you need to ensure that the upstream of the reverse proxy points to the correct address. For details of this mechanism, see Deployment with multiple PD instances.

When you use the TiUP tool for deployment, execute the following command to get the actual TiDB Dashboard address (replace CLUSTER_NAME with your cluster name):

tiup cluster display CLUSTER_NAME --dashboard

The output is the actual TiDB Dashboard address. A sample is as follows:

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).

Upgrade TiUP Cluster

tiup update --self
tiup update cluster --force

Step 2: Configure the reverse proxy

Use HAProxy

When you use HAProxy as the reverse proxy, take the following steps:

Use reverse proxy for TiDB Dashboard on the 8033 port (for example). In the HAProxy configuration file, add the following configuration:
```
frontend tidb_dashboard_front
  bind *:8033
  use_backend tidb_dashboard_back if { path /dashboard } or { path_beg /dashboard/ }
backend tidb_dashboard_back
  mode http
  server tidb_dashboard 192.168.0.123:2379
```
Replace 192.168.0.123:2379 with IP and port of the actual address of the TiDB Dashboard obtained in Step 1.

Warning

You must retain the if part in the use_backend directive to ensure that services only in this path are behind reverse proxy; otherwise, security risks might be introduced. See Secure TiDB Dashboard.
Restart HAProxy for the configuration to take effect.
Test whether the reverse proxy is effective: access the /dashboard/ address on the 8033 port of the machine where HAProxy is located (such as http://example.com:8033/dashboard/) to access TiDB Dashboard.

Use NGINX

When you use NGINX as the reverse proxy, take the following steps:

Use reverse proxy for TiDB Dashboard on the 8033 port (for example). In the NGINX configuration file, add the following configuration:
```
server {
    listen 8033;
    location /dashboard/ {
    proxy_pass http://192.168.0.123:2379/dashboard/;
    }
}
```
Replace http://192.168.0.123:2379/dashboard/ with the actual address of the TiDB Dashboard obtained in Step 1.

Warning

You must keep the /dashboard/ path in the proxy_pass directive to ensure that only the services under this path are reverse proxied. Otherwise, security risks will be introduced. See Secure TiDB Dashboard.
Reload NGINX for the configuration to take effect.
```
sudo nginx -s reload
```
Test whether the reverse proxy is effective: access the /dashboard/ address on the 8033 port of the machine where NGINX is located (such as http://example.com:8033/dashboard/) to access TiDB Dashboard.

Customize path prefix

TiDB Dashboard provides services by default in the /dashboard/ path, such as http://example.com:8033/dashboard/, which is the case even for reverse proxies. To configure the reverse proxy to provide the TiDB Dashboard service with a non-default path, such as http://example.com:8033/foo/ or http://example.com:8033/, take the following steps.

Step 1: Modify PD configuration to specify the path prefix of TiDB Dashboard service

Modify the public-path-prefix configuration item in the [dashboard] category of the PD configuration to specify the path prefix of the TiDB Dashboard service. After this item is modified, restart the PD instance for the modification to take effect.

For example, if the cluster is deployed using TiUP and you want the service to run on http://example.com:8033/foo/, you can specify the following configuration:

server_configs:
  pd:
    dashboard.public-path-prefix: /foo

Modify configuration when deploying a new cluster using TiUP

If you are deploying a new cluster, you can add the configuration above to the topology.yaml TiUP topology file and deploy the cluster. For specific instruction, see TiUP deployment document.

Modify configuration of a deployed cluster using TiUP

For a deployed cluster:

Open the configuration file of the cluster in the edit mode (replace CLUSTER_NAME with the cluster name).
```
tiup cluster edit-config CLUSTER_NAME
```

Modify or add configuration items under the pd configuration of server_configs. If no server_configs exists, add it at the top level:

monitored:
  ...
server_configs:
  tidb: ...
  tikv: ...
  pd:
    dashboard.public-path-prefix: /foo
  ...

The configuration file after the modification is similar to the following file:

server_configs:
  pd:
    dashboard.public-path-prefix: /foo
  global:
    user: tidb
    ...

monitored:
  ...
server_configs:
  tidb: ...
  tikv: ...
  pd:
    dashboard.public-path-prefix: /foo

Perform a rolling restart to all PD instances for the modified configuration to take effect (replace CLUSTER_NAME with your cluster name):
```
tiup cluster reload CLUSTER_NAME -R pd
```

See Common TiUP Operations - Modify the configuration for details.

If you want that the TiDB Dashboard service is run in the root path (such as http://example.com:8033/), use the following configuration:

server_configs:
  pd:
    dashboard.public-path-prefix: /

Warning

After the modified and customized path prefix takes effect, you cannot directly access TiDB Dashboard. You can only access TiDB Dashboard through a reverse proxy that matches the path prefix.

Step 2: Modify the reverse proxy configuration

Use HAProxy

Taking http://example.com:8033/foo/ as an example, the corresponding HAProxy configuration is as follows:

frontend tidb_dashboard_front
  bind *:8033
  use_backend tidb_dashboard_back if { path /foo } or { path_beg /foo/ }
backend tidb_dashboard_back
  mode http
  http-request set-path %[path,regsub(^/foo/?,/dashboard/)]
  server tidb_dashboard 192.168.0.123:2379

Replace 192.168.0.123:2379 with IP and port of the actual address of the TiDB Dashboard obtained in Step 1.

Warning

You must retain the if part in the use_backend directive to ensure that services only in this path are behind reverse proxy; otherwise, security risks might be introduced. See Secure TiDB Dashboard.

If you want that the TiDB Dashboard service is run in the root path (such as http://example.com:8033/), use the following configuration:

frontend tidb_dashboard_front
  bind *:8033
  use_backend tidb_dashboard_back
backend tidb_dashboard_back
  mode http
  http-request set-path /dashboard%[path]
  server tidb_dashboard 192.168.0.123:2379

Modify the configuration and restart HAProxy for the modified configuration to take effect.

Use NGINX

Taking http://example.com:8033/foo/ as an example, the corresponding NGINX configuration is as follows:

server {
  listen 8033;
  location /foo/ {
    proxy_pass http://192.168.0.123:2379/dashboard/;
  }
}

Replace http://192.168.0.123:2379/dashboard/ with the actual address of the TiDB Dashboard obtained in Step 1.

Warning

You must retain the /dashboard/ path in the proxy_pass directive to ensure that services only in this path are behind reverse proxy; otherwise, security risks might be introduced. See Secure TiDB Dashboard.

If you want that the TiDB Dashboard service is run in the root path (such as http://example.com:8033/), use the following configuration:

server {
  listen 8033;
  location / {
    proxy_pass http://192.168.0.123:2379/dashboard/;
  }
}

Modify the configuration and restart NGINX for the modified configuration to take effect.

sudo nginx -s reload

What’s next

To learn how to enhance the security of TiDB Dashboard, such as configuring a firewall, see Secure TiDB Dashboard.