Skip to main content
Version: Mosquitto 2.8

Cluster Management

Cluster Management operations

Available API Paths​

Path: /api/cluster-management/clusters​

Methods​

GET​

Retrieve a list of all clusters. Can be accessed by viewer, editor, admin, and monitoringViewer

Responses

Status Description Response Content or Scheme
200 An array of all clusters 
{
  "clustername": {
    "type": "string"
  },
  "description": {
    "type": "string"
  },
  "nodes": {
    "type": "array",
    "description": "array with all the nodes of the cluster",
    "items": {
      "$ref": "#/components/schemas/HAClusterNode"
    }
  },
  "state": {
    "type": "string",
    "description": "State of the cluster. Either active when all nodes are healthy, inactive when cluster doesn't respond, or degraded when one or more ndoes are down",
    "enum": [
      "active",
      "inactive",
      "degraded"
    ]
  }
}

Example

{
  "clustername": "promosquittoha3",
  "description": "Pro Mosquitto HA 3-Node Cluster",
  "nodes": [
    {
      "port": 7000,
      "nodeid": 1,
      "address": "111.111.5.1",
      "broker": "mosquitto1",
      "connection": {
        "url": "mqtt://111.111.5.1:1885"
      },
      "ha": {
        "clustername": "promosquittoha3",
        "uuid": "E4F345F8-6905-1ED4-16B9-0C9028761AE1",
        "nodes": [
          {
            "address": "111.111.5.2",
            "port": 7000,
            "nodeid": 2
          },
          {
            "address": "111.111.5.3",
            "port": 7000,
            "nodeid": 3
          },
          {
            "address": "111.111.5.1",
            "port": 7000,
            "nodeid": 1
          }
        ],
        "version": 1,
        "syncmode": "full"
      },
      "leader": true,
      "clustername": "promosquittoha3",
      "uuid": "E4F345F8-6905-1ED4-16B9-0C9028761AE1",
      "log_index": 96
    },
    {
      "port": 7000,
      "nodeid": 2,
      "address": "111.111.5.2",
      "broker": "mosquitto2",
      "connection": {
        "url": "mqtt://111.111.5.2:1885"
      },
      "ha": {
        "clustername": "promosquittoha3",
        "uuid": "E4F345F8-6905-1ED4-16B9-0C9028761AE1",
        "nodes": [
          {
            "address": "111.111.5.3",
            "port": 7000,
            "nodeid": 3
          },
          {
            "address": "111.111.5.1",
            "port": 7000,
            "nodeid": 1
          },
          {
            "address": "111.111.5.2",
            "port": 7000,
            "nodeid": 2
          }
        ],
        "version": 1,
        "syncmode": "full"
      },
      "leader": false,
      "clustername": "promosquittoha3",
      "uuid": "E4F345F8-6905-1ED4-16B9-0C9028761AE1"
    },
    {
      "port": 7000,
      "nodeid": 3,
      "address": "111.111.5.3",
      "broker": "mosquitto3",
      "connection": {
        "url": "mqtt://111.111.5.3:1885"
      },
      "ha": {
        "clustername": "promosquittoha3",
        "uuid": "E4F345F8-6905-1ED4-16B9-0C9028761AE1",
        "nodes": [
          {
            "address": "111.111.5.2",
            "port": 7000,
            "nodeid": 2
          },
          {
            "address": "111.111.5.1",
            "port": 7000,
            "nodeid": 1
          },
          {
            "address": "111.111.5.3",
            "port": 7000,
            "nodeid": 3
          }
        ],
        "version": 1,
        "syncmode": "full"
      },
      "leader": false,
      "clustername": "promosquittoha3",
      "uuid": "E4F345F8-6905-1ED4-16B9-0C9028761AE1"
    }
  ],
  "state": "active"
}
Status Description Response Content or Scheme
401 Access to resource is denied. User not authenticated (logged in) or session expired 
{
  "code": {
    "type": "string",
    "enum": [
      "UNAUTHORIZED"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "Unauthorized"
    ],
    "description": "Message of the error"
  }
}
403 User does not have enough permissions to access the resource 
{
  "code": {
    "type": "string",
    "enum": [
      "NOT_ALLOWED"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "Not allowed",
      "You don't have enough user rights to perform this operation. You might not have permission to access the brokers"
    ],
    "description": "Message of the error"
  }
}
404 Plugin is not enabled or not found 
{
  "code": {
    "type": "string",
    "enum": [
      "NOT_FOUND"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "Plugin not found"
    ],
    "description": "Message of the error"
  }
}
410 Requested entity does not exists or was removed 
{
  "code": {
    "type": "string",
    "enum": [
      "GONE"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "Broker \"<brokerId>\" not found",
      "Cluster does not exist"
    ],
    "description": "Message of the error"
  }
}
500 An internal server error has occured 
{
  "code": {
    "type": "string",
    "enum": [
      "INTERNAL_ERROR",
      "SOMETHING_WRONG"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "An internal server error occurred",
      "Cluster node assiciated with broker \"<brokerId>\" not connected"
    ],
    "description": "Message of the error"
  }
}

Path: /api/cluster-management/status/clusters​

Methods​

GET​

Retrieve the status of all clusters. Can be accessed by viewer, editor, admin, and monitoringViewer

Responses

Status Description Response Content or Scheme
200 Object containing an array of cluster statuses 
{
  "clusters": {
    "type": "array",
    "items": {
      "$ref": "#/components/schemas/HAClusterStatus"
    }
  }
}
401 Access to resource is denied. User not authenticated (logged in) or session expired 
{
  "code": {
    "type": "string",
    "enum": [
      "UNAUTHORIZED"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "Unauthorized"
    ],
    "description": "Message of the error"
  }
}
403 User does not have enough permissions to access the resource 
{
  "code": {
    "type": "string",
    "enum": [
      "NOT_ALLOWED"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "Not allowed",
      "You don't have enough user rights to perform this operation. You might not have permission to access the brokers"
    ],
    "description": "Message of the error"
  }
}
404 Plugin is not enabled or not found 
{
  "code": {
    "type": "string",
    "enum": [
      "NOT_FOUND"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "Plugin not found"
    ],
    "description": "Message of the error"
  }
}
410 Requested entity does not exists or was removed 
{
  "code": {
    "type": "string",
    "enum": [
      "GONE"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "Broker \"<brokerId>\" not found",
      "Cluster does not exist"
    ],
    "description": "Message of the error"
  }
}
500 An internal server error has occured 
{
  "code": {
    "type": "string",
    "enum": [
      "INTERNAL_ERROR",
      "SOMETHING_WRONG"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "An internal server error occurred",
      "Cluster node assiciated with broker \"<brokerId>\" not connected"
    ],
    "description": "Message of the error"
  }
}

Path: /api/cluster-management/clusters/{clusterName}​

Methods​

GET​

Retrieve a specific cluster by its clustername. Can be accessed by viewer, editor, admin, and monitoringViewer

Parameters

NameLocationTypeRequiredDescription
clusterNamepathstringtrueName of the cluster to retrieve

Responses

Status Description Response Content or Scheme
200 Object which represents a cluster with all it's nodes 
{
  "json": {
    "$ref": "#/components/schemas/HACluster"
  }
}
401 Access to resource is denied. User not authenticated (logged in) or session expired 
{
  "code": {
    "type": "string",
    "enum": [
      "UNAUTHORIZED"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "Unauthorized"
    ],
    "description": "Message of the error"
  }
}
403 User does not have enough permissions to access the resource 
{
  "code": {
    "type": "string",
    "enum": [
      "NOT_ALLOWED"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "Not allowed",
      "You don't have enough user rights to perform this operation. You might not have permission to access the brokers"
    ],
    "description": "Message of the error"
  }
}
404 Plugin is not enabled or not found 
{
  "code": {
    "type": "string",
    "enum": [
      "NOT_FOUND"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "Plugin not found"
    ],
    "description": "Message of the error"
  }
}
410 Requested entity does not exists or was removed 
{
  "code": {
    "type": "string",
    "enum": [
      "GONE"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "Broker \"<brokerId>\" not found",
      "Cluster does not exist"
    ],
    "description": "Message of the error"
  }
}
500 An internal server error has occured 
{
  "code": {
    "type": "string",
    "enum": [
      "INTERNAL_ERROR",
      "SOMETHING_WRONG"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "An internal server error occurred",
      "Cluster node assiciated with broker \"<brokerId>\" not connected"
    ],
    "description": "Message of the error"
  }
}

Path: /api/cluster-management/mqtt​

Methods​

POST​

Send a command to a cluster node (commands get redirected to the leader) as defined in Mosquitto HA Cedalo documentation. Must be admin to access

Parameters

NameLocationTypeRequiredDescription
bodybodyundefinedtrueBroker ID and command to send

Responses

Status Description Response Content or Scheme
200 Result from the cluster 
{
  "json": {
    "$ref": "#/components/schemas/HAClusterCommandResponse"
  }
}
400 Input data invalid 
{
  "code": {
    "type": "string",
    "enum": [
      "INVALID"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "Invalid",
      "Broker \"<brokerId>\" not found",
      "BaseMosquittoClient: Timeout"
    ],
    "description": "Message of the error"
  }
}
401 Access to resource is denied. User not authenticated (logged in) or session expired 
{
  "code": {
    "type": "string",
    "enum": [
      "UNAUTHORIZED"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "Unauthorized"
    ],
    "description": "Message of the error"
  }
}
403 User does not have enough permissions to access the resource 
{
  "code": {
    "type": "string",
    "enum": [
      "NOT_ALLOWED"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "Not allowed",
      "You don't have enough user rights to perform this operation. You might not have permission to access the brokers"
    ],
    "description": "Message of the error"
  }
}
404 Plugin is not enabled or not found 
{
  "code": {
    "type": "string",
    "enum": [
      "NOT_FOUND"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "Plugin not found"
    ],
    "description": "Message of the error"
  }
}
410 Requested entity does not exists or was removed 
{
  "code": {
    "type": "string",
    "enum": [
      "GONE"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "Broker \"<brokerId>\" not found",
      "Cluster does not exist"
    ],
    "description": "Message of the error"
  }
}
500 An internal server error has occured 
{
  "code": {
    "type": "string",
    "enum": [
      "INTERNAL_ERROR",
      "SOMETHING_WRONG"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "An internal server error occurred",
      "Cluster node assiciated with broker \"<brokerId>\" not connected"
    ],
    "description": "Message of the error"
  }
}