Using ClusterControl RPC API

ClusterControl provides an RPC API interface for the ClusterControl controller (CMON).

Please note that the RPCv2 API calls are only available via secure (TLS) connections, where encryption is mandatory. The RPCv2 also uses an authentication call, and very few of the calls are available to be used without authenticating first.

By default, the encrypted communication can be used through port 9501 and the RPC v2 requests are server served on the /v2 path (e.g. /v2/clusters).

Accessing the RPC API

By default, the ClusterControl RPC API interface (port 9501) listens to localhost. This means, only local user is able to access the API interface and additional steps are required to expose this interface publicly. See Remote access.

Local access

Access the ClusterControl IP address on port 9501 as shown in the example below:
```
curl -k https://127.0.0.1:9501/v2
```

You should get the following reply:

{
    "controller_id": "c469a80f-8ad9-4e7b-8f5d-82346c671609",
    "error_string": "Invalid operation '' on '/v2/info'.",
    "request_operation": "",
    "request_path": [
        "v2"
    ],
    "request_processed": "2025-04-15T17:55:49.409Z",
    "request_status": "InvalidRequest"
}

Despite the error, it means that you are able to connect to the interface and get a proper reply. See Authenticating with the API to start sending a proper request.

Remote access

To expose the RPC API remotely, include the IP address of the host in the RPC_BIND_ADDRESSES variables inside /etc/default/cmon. The following commands should be executed on the ClusterControl server.

Add the primary IP address of the ClusterControl node inside /etc/default/cmon:
```
RPC_BIND_ADDRESSES="192.168.20.10,127.0.0.1"
```
Restart cmon service to make sure ClusterControl listens on port 9501 for both IP addresses defined above:
```
systemctl restart cmon
```

Make sure you see port 9501 is listening to the configured IP addresses.

$ netstat -tulpn | grep 9501
tcp        0      0 127.0.0.1:9501          0.0.0.0:*               LISTEN      1681928/cmon
tcp        0      0 192.168.20.10:9501      0.0.0.0:*               LISTEN      1681928/cmon

Access the ClusterControl IP address on port 9501 as shown in the example below:
```
curl -k https://192.168.61.210:9501/v2
```

You should get the following reply:

{
    "controller_id": "c469a80f-8ad9-4e7b-8f5d-82346c671609",
    "error_string": "Invalid operation '' on '/v2/info'.",
    "request_operation": "",
    "request_path": [
        "v2"
    ],
    "request_processed": "2025-04-15T17:55:49.409Z",
    "request_status": "InvalidRequest"
}

Despite the error, it means that you are able to connect to the interface and get a proper reply. See Authenticating with the API to start sending a proper request.

Authenticating with the API

If you would like to access the cluster object via HTTP, send the request to the RPCv2 API accessible on port 9501 (TLS enabled). Use one of the following two methods:

Pass the username and password inside a nested authenticate method in an operation:

curl -k 'https://192.168.20.10:9501/v2/clusters' \
-XPOST -d \
'{"operation": "getAllClusterInfo", 
"authenticate": 
{"password": "s3cr3tP455","username": "readeruser"}}'

This is the recommended way and is used by all our applications to connect to the ClusterControl controller. Users need to maintain cookies/sessions after the first authentication and send other requests with the corresponding cookies/session. To obtain a session, use the authenticateWithPassword operation and connect to the v2/auth endpoint:
```
curl -k 'https://192.168.20.10:9501/v2/auth' \
-XPOST -d \ 
'{"operation":"authenticateWithPassword", 
"user_name":"readeruser", 
"password":"s3cr3tP455"}' \
-c cookies.jar
```
Then, include cookies.jar with every subsequent read-only request:
```
curl -k 'https://192.168.20.10:9501/v2/clusters' \
-XPOST -d \
'{"operation":"getallclusterinfo"}' \
-b cookies.jar
```

Successful request

If the RPC call is successful, you should receive a response with "request_status": "Ok", similar to the following output:

{
    "controller_id": "683e2b4b-038f-4cf7-93a0-4c3f95b3db70",
    "request_processed": "2024-11-07T19:33:12.701Z",
    "request_status": "Ok",
    "request_user_id": 5,
    "total": 3,
    "clusters":
    [
    ...json content...
    ],
    "debug_messages":
    [
        "RPC V2 authenticated user is 'readeruser'."
    ]
}

Failed request

In this example, the user that we use is only having a read-only permission. If the user is trying to execute a non-read-only request, for example, sending a stop node job that requires an "execute" permission:

curl -k 'https://192.168.20.10:9501/v2/jobs' \
    -XPOST -d '{"cluster_id": 21, "job": {"class_name": "CmonJobInstance",
    "job_spec":
    {"command": "stop",
    "job_dat":{"clusterid": 21,
    "node":{"hostname": "192.168.20.53"}}}},
    "operation": "createJobInstance"}' \
    -b cookies.jar

The reply should return "request_status": "AccessDenied", similar to the following output:

{
    "controller_id": "9eb8b1d1-f9d1-439e-945e-108982812bee",
    "error_string": "Execute access to cluster 21 for user readeruser is denied.",
    "request_processed": "2021-05-04T07:01:38.342Z",
    "request_status": "AccessDenied",
    "request_user_id": 7,
    "debug_messages":
    [
        "RPC V2 authenticated user is 'readeruser'."
    ]
}