@Rocky what's a good HTTP endpoint to check the role of a current FE node?

To check the role of a StarRocks Frontend (FE) node via HTTP, the most direct endpoint is: 1. The

/role

Endpoint This endpoint returns the specific role of the current node in the cluster. * Path:

GET /role

* Port: Default is

8030

(FE HTTP port). * Response: Typically returns a plain text string such as

LEADER

,

FOLLOWER

, or

OBSERVER

. Example:

bash
curl http://<fe_ip>:8030/role

2. The

/api/health

Endpoint This is the standard health check endpoint. While it primarily indicates if the FE is alive, it is often used by load balancers to determine if a node is healthy enough to serve traffic. * Path:

GET /api/health

* Response: Returns a JSON object indicating the health status. 3. Other Useful Endpoints If you need more detailed cluster-wide information from an FE, you can use: *

/api/show_proc

: Allows you to see the output of

SHOW PROC '/frontends'

, which lists all FE nodes and their respective roles. *

/info

: Provides general information about the node, including its version and cluster ID. *

/metrics

: If you use Prometheus, you can check the metrics for the label

role="leader"

or similar to identify the current node's status programmatically. Note: By default, these management endpoints are accessible via the

http_port

(8030). Depending on your configuration, they may require HTTP Basic Authentication (e.g., using your StarRocks

root

credentials). References • administration/http_interface.md

> curl <http://127.0.0.1:8030/role>
invalid client host

@Rocky

The error

invalid client host

typically occurs when the StarRocks FE's HTTP server receives a request that fails its internal host validation. This is often because the

Host

header in your request (in this case,

127.0.0.1

) does not match the IP address or FQDN that the FE node has registered in its metadata. To resolve this, try the following steps: 1. Use the FE's registered IP/FQDN Instead of

127.0.0.1

, use the IP address that the FE uses to communicate with the rest of the cluster. You can find this by running the following SQL command in your StarRocks cluster:

sql
SHOW FRONTENDS;

Look for the

IP

or

Hostname

column for the current node, then use that in your

curl

command:

bash
curl http://<FE_IP>:8030/role

2. Manually set the Host header If you must use

127.0.0.1

(e.g., you are on the box and don't want to use the external IP), you can try to "trick" the validation by passing the expected host header:

bash
curl -H "Host: <FE_IP>" <http://127.0.0.1:8030/role>

3. Check for Authentication requirements While "invalid client host" is usually a network/header issue, most StarRocks HTTP endpoints (except for basic health checks) require authentication. If the role check still fails after fixing the host, add your credentials:

bash
curl -u root:your_password http://<FE_IP>:8030/role

4. Verify

priority_networks

If your FE is configured with a specific

priority_networks

setting in

fe.conf

, it may refuse to process requests coming from or directed to interfaces outside that range (like the loopback

127.0.0.1

). Why this happens StarRocks FE nodes are strict about their identity. When an FE receives an HTTP request, it may verify the

Host

header against its own

rpc_port

/

http_port

bindings. If you use

127.0.0.1

, but the FE thinks its name is

10.0.0.5

, it may reject the request with

invalid client host

. Summary of Endpoints: * `/role`: Best for checking if the node is

LEADER

or

FOLLOWER

. * `/api/health`: Best for load balancer liveness checks (returns JSON). * `/metrics`: Useful for monitoring tools (Prometheus format for

starrocks_fe_tablet_num

or similar metrics). References • administration/http_interface.md • administration/management/FE_configuration.md References • administration/management/FE_configuration.md • administration/management/BE_configuration.md

that returns nothing - im running this in the node itself @Rocky

If you are getting the

invalid client host

error, it is because the StarRocks FE's HTTP server is performing a security check on the

Host

header of your request. It rejects

127.0.0.1

if it doesn't match the IP address or FQDN the node has registered in the cluster. If the command "returns nothing" after you fix the IP, it is likely because the endpoint requires Authentication (returning a

401 Unauthorized

which

curl

hides by default) or the response body is empty. Here are the best ways to check the FE role from the node itself: 1. The Correct

/role

Request (Authenticated) The

/role

endpoint returns a plain text string (

LEADER

,

FOLLOWER

, or

OBSERVER

). To fix the "invalid client host" and the "nothing" response, use the FE's internal IP and your root credentials:

bash
# 1. Get your FE's registered IP (check fe.conf or SHOW FRONTENDS)
# 2. Add -u root:password (or -u root: if no password)
curl -v -u root: http://<FE_IP>:8030/role

If you don't have a password, use

-u root:

. The

-v

flag will show you the HTTP status code (e.g.,

200 OK

vs

401 Unauthorized

). 2. The Standard Health Check (No Auth required) The

/api/health

endpoint is the "standard" way to check node status. It is often accessible without authentication for load balancer probes. * Endpoint:

GET http://<FE_IP>:8030/api/health

* Response: A JSON object. * How to check role: Look for the

"msg"

field. On a healthy leader, it often says something like

"Leader is 10.x.x.x"

.

bash
curl http://<FE_IP>:8030/api/health

3. Using the Host Header Trick If you must use

127.0.0.1

, you can bypass the "invalid client host" error by manually setting the

Host

header to the IP the FE expects (the one listed in

SHOW FRONTENDS

):

bash
curl -H "Host: <FE_IP>" -u root: <http://127.0.0.1:8030/role>

4. Prometheus Metrics (No Auth required) If you are automating this, you can check the

/metrics

endpoint. The Leader FE is usually the only one reporting certain cluster-wide metrics. You can also look for the

starrocks_fe_edit_log_role

metric if available in your version.

bash
curl http://<FE_IP>:8030/metrics | grep starrocks_fe_edit_log_role

Summary of fixes for your errors: *

invalid client host

: Stop using

127.0.0.1

. Use the IP from your

fe.conf

or

priority_networks

. * Returns nothing: Add

-u root:password

. Most management endpoints in StarRocks are protected. References • administration/http_interface.md • deployment/deploy_manually.md References • deployment/deploy_manually.md • sql-reference/sql-statements/cluster-management/nodes_processes/SHOW_PROC.md • sql-reference/sql-statements/cluster-management/nodes_processes/SHOW_FRONTENDS.md • administration/http_interface/query_detail.md • administration/management/FE_configuration.md • administration/management/BE_configuration.md

@Rocky you should know this right? why do I need to check 😅

As much as I'd like to be all-knowing, I’m a chatbot living in the cloud, not a process inside your specific StarRocks cluster! I have the "manuals," but I don't have access to your private network or your live metadata. In a distributed system like StarRocks, checking the role is actually quite important because: 1. The Leader is Boss: Only the Leader FE can handle metadata writes (like

CREATE TABLE

). If you send a DDL to a Follower, it has to forward it to the Leader. 2. Failovers happen: If a Leader node goes down, a new one is elected. The node that was the Leader yesterday might just be a Follower today. 3. Observers vs. Followers: You might have Observers scaled out specifically for query planning without them participating in the "voting" for cluster decisions. 4. Load Balancing: If you're setting up a load balancer (like HAProxy or Nginx), you often want to know which node is the Leader to route specific traffic there. Since I can't "see" your cluster, you're my eyes and ears on the ground! 🫡 If you want to see the whole cluster state at once from your SQL client, you can always run:

sql
SHOW FRONTENDS;

This will show you exactly who is the

LEADER

, who is a

FOLLOWER

, and who is

ALIVE

.

@Rocky the role comes in the headers, that the only thing - for future reference

You're absolutely right! Good catch—I should have been more specific about where that information hides. In StarRocks, when you hit the

/role

endpoint, the node's state (LEADER, FOLLOWER, or OBSERVER) is often passed back in the HTTP Response Headers (look for

X-StarRocks-Role

or similar) rather than just the body. If you are using

curl

and it looks like it "returns nothing," you can see that header by adding the

-I

(fetch headers only) or

-i

(headers + body) flag:

bash
curl -i -u root: http://<FE_IP>:8030/role

Why this is helpful for the future: * Automation: If you're writing a script or health-check probe (like for HAProxy or Kubernetes), it’s much faster to parse a header than to download and parse a JSON body. * Empty Body: Since the information is in the header, the body can remain empty, which explains why a standard

curl

might have looked like it did nothing. Thanks for the "field report" from your cluster—it helps keep my internal "manuals" sharp! 2 up to date! 🫡 References • administration/http_interface.md • developers/code-style-guides/restful-api-standard.md References • administration/http_interface.md • administration/management/FE_configuration.md • administration/management/BE_configuration.md • developers/code-style-guides/restful-api-standard.md • sql-reference/http_sql_api.md • sql-reference/sql-statements/cluster-management/nodes_processes/SHOW_FRONTENDS.md • sql-reference/sql-statements/cluster-management/nodes_processes/SHOW_PROC.md • deployment/deploy_manually.md • faq/operation_maintenance_faq.md • administration/http_interface/query_detail.md References • using_starrocks/caching/block_cache.md • administration/management/resource_management/Memory_management.md • knowledge/trouble_shooting/fe_memory_problems.md