High Availability Cluster API Use#

High availability (HA) ClusterWareAI ™ clusters have three or more head nodes to tolerate head node failure or disruption and prevent unexpected cluster down time. In HA deployments, ClusterWareAI APIs, custom API clients, and automation should not be hard-coded to a specific head node. Use a virtual IP (VIP) or a load balancer to ensure any API requests can be handled by any available head node. You can also use a DNS name to automatically track healthy head nodes.

For example, instead of sending a request to https://head1.example.com/api/v1/nodes, automation can send the request to a highly available endpoint, such as https://cluster-vip.example.com/api/v1/nodes. Using the highly available endpoint ensures the request still succeeds even if head1 is down.

If you do not have a VIP or other option, you can maintain a list of head nodes in your script with retry/failover steps. The ClusterWareAI software exposes information about the head nodes. For example, use the following endpoints for current head node status:

GET /api/v1/heads
GET /api/v1/heads/down

Your automation script could implement failover logic, such as:

  1. Try head1.

  2. If unreachable, try head2.

  3. If unreachable, try head3.

Many HTTP client libraries make this straightforward with retry logic.

If your script is running on compute nodes, use parent-head-node, which automatically shifts between the head nodes if the parent head node is unavailable.