Cluster API

NOTE: Requests to the cluster API require you to authenticate with a Sensu access token or API key. The code examples in this document use the environment variable $SENSU_API_KEY to represent a valid API key in API requests.

Get all cluster data

The /cluster/members API endpoint provides HTTP GET access to Sensu cluster data.

Example

The following example demonstrates a request to the /cluster/members API endpoint, resulting in a JSON map that contains a Sensu cluster definition.

curl -X GET \
http://127.0.0.1:8080/api/core/v2/cluster/members \
-H "Authorization: Key $SENSU_API_KEY" \

HTTP/1.1 200 OK
{
  "header": {
    "cluster_id": 4255616304056076734,
    "member_id": 9882886658148554927,
    "raft_term": 2
  },
  "members": [
    {
      "ID": 9882886658148554927,
      "name": "default",
      "peerURLs": [
        "http://127.0.0.1:2380"
      ],
      "clientURLs": [
        "http://127.0.0.1:2379"
      ]
    }
  ]
}

API Specification

/cluster/members (GET)
description Returns the etcd cluster definition.
example url http://hostname:8080/api/core/v2/cluster/members
query parameters timeout: Defines the timeout when querying etcd. Default is 3.
response type Map
response codes
  • Success: 200 (OK)
  • Error: 500 (Internal Server Error)
example output 
{
  "header": {
    "cluster_id": 4255616304056076734,
    "member_id": 9882886658148554927,
    "raft_term": 2
  },
  "members": [
    {
      "ID": 9882886658148554927,
      "name": "default",
      "peerURLs": [
        "http://127.0.0.1:2380"
      ],
      "clientURLs": [
        "http://127.0.0.1:2379"
      ]
    }
  ]
}

Create a new cluster member

The /cluster/members API endpoint provides HTTP POST access to create a Sensu cluster member.

Example

curl -X POST \
-H "Authorization: Key $SENSU_API_KEY" \
http://127.0.0.1:8080/api/core/v2/cluster/members?peer-addrs=http://127.0.0.1:2380

HTTP/1.1 200 OK
{
  "header": {
    "cluster_id": 4255616304056077000,
    "member_id": 9882886658148555000,
    "raft_term": 2
  },
  "members": [
    {
      "ID": 9882886658148555000,
      "name": "default",
      "peerURLs": [
        "http://127.0.0.1:2380"
      ],
      "clientURLs": [
        "http://localhost:2379"
      ]
    }
  ]
}

API Specification

/cluster/members/:member (POST)
description Creates a cluster member.
example url http://hostname:8080/api/core/v2/cluster/members?peer-addrs=http://127.0.0.1:2380
query parameters
  • Required: peer-addrs (a comma-delimited list of peer addresses).
response codes
  • Success: 200 (OK)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)

Create or update a cluster member

The /cluster/members/:member API endpoint provides HTTP PUT access to create or update a cluster member, by cluster member ID.

Example

curl -X PUT \
-H "Authorization: Key $SENSU_API_KEY" \
http://127.0.0.1:8080/api/core/v2/cluster/members/8927110dc66458af?peer-addrs=http://127.0.0.1:2380

HTTP/1.1 200 OK
{
  "header": {
    "cluster_id": 4255616304056077000,
    "member_id": 9882886658148555000,
    "raft_term": 2
  },
  "members": [
    {
      "ID": 9882886658148555000,
      "name": "default",
      "peerURLs": [
        "http://127.0.0.1:2380"
      ],
      "clientURLs": [
        "http://localhost:2379"
      ]
    }
  ]
}

API Specification

/cluster/members/:member (PUT)
description Creates or updates a cluster member.
example url http://hostname:8080/api/core/v2/cluster/members/8927110dc66458af?peer-addrs=http://127.0.0.1:2380
url parameters Required: 8927110dc66458af (hex-encoded uint64 cluster member ID generated using sensuctl cluster member-list).
query parameters Required: peer-addrs (a comma-delimited list of peer addresses).
response codes
  • Success: 200 (OK)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)

Delete a cluster member

The /cluster/members/:member API endpoint provides HTTP DELETE access to remove a Sensu cluster member.

Example

The following example shows a request to the /cluster/members/:member API endpoint to remove the Sensu cluster member with the ID 8927110dc66458af, resulting in a successful HTTP 204 No Content response.

curl -X DELETE \
-H "Authorization: Key $SENSU_API_KEY" \
http://127.0.0.1:8080/api/core/v2/namespaces/default/cluster/members/8927110dc66458af

HTTP/1.1 204 No Content

API Specification

/cluster/members/:member (DELETE)
description Removes a member from a Sensu cluster (specified by the member ID).
example url http://hostname:8080/api/core/v2/cluster/members/8927110dc66458af
url parameters
  • 8927110dc66458af (required): Required hex-encoded uint64 cluster member ID generated using sensuctl cluster member-list
response codes
  • Success: 204 (No Content)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)

Get a cluster ID

The /cluster/id API endpoint provides HTTP GET access to the Sensu cluster ID.

Example

The following example demonstrates a request to the /cluster/id API endpoint, resulting in a string that contains the Sensu cluster ID.

curl -X GET \
 -H "Authorization: Key $SENSU_API_KEY" \
http://127.0.0.1:8080/api/core/v2/cluster/id

HTTP/1.1 200 OK
"23481e76-5844-4d07-b714-6e2ffbbf9315"

API Specification

/cluster/id (GET)
description Returns the unique Sensu cluster ID.
example url http://hostname:8080/api/core/v2/cluster/id
query parameters timeout: Defines the timeout when querying etcd. Default is 3.
response type String
response codes
  • Success: 200 (OK)
  • Error: 500 (Internal Server Error)
example output 
"23481e76-5844-4d07-b714-6e2ffbbf9315"