Skip to main content

Advanced Setup

For production environments requiring high availability (HA) and horizontal scalability, the Kadeck can be deployed as a cluster.

This configuration ensures:

  • No single point of failure
  • Continuous availability even during node failures
  • Dynamic scaling of additional Kadeck instances

Overview of Cluster Architecture​

A Kadeck cluster consists of:

  • Master Nodes — Static nodes responsible for maintaining cluster stability and coordination.
  • Auto-Scaling Nodes — Dynamic instances that join the cluster at runtime to handle additional load.

Master Node Configuration​

Master nodes form the backbone of the cluster. At least three master nodes are recommended to tolerate up to two simultaneous failures.

1. Define the Master Nodes​

Decide which instances will act as masters. Example configuration:

NodeHostnamePort
Kadeck-1kadeck-12551
Kadeck-2kadeck-22552
Kadeck-3kadeck-32553

All master nodes must know about each other.

2. Configure Each Master Node​

Set the following environment variables on each master:

Example: Kadeck-1​

XEOTEK_KADECK_CLUSTER_NODES=kadeck-1:2551,kadeck-2:2552,kadeck-3:2553
XEOTEK_KADECK_CLUSTER_HOSTNAME=kadeck-1
XEOTEK_KADECK_CLUSTER_PORT=2551

Example: Kadeck-2​

XEOTEK_KADECK_CLUSTER_NODES=kadeck-1:2551,kadeck-2:2552,kadeck-3:2553
XEOTEK_KADECK_CLUSTER_HOSTNAME=kadeck-2
XEOTEK_KADECK_CLUSTER_PORT=2552

Example: Kadeck-3​

XEOTEK_KADECK_CLUSTER_NODES=kadeck-1:2551,kadeck-2:2552,kadeck-3:2553
XEOTEK_KADECK_CLUSTER_HOSTNAME=kadeck-3
XEOTEK_KADECK_CLUSTER_PORT=2553

Important:
All masters must list the same XEOTEK_KADECK_CLUSTER_NODES.
Hostnames must resolve correctly inside the Kubernetes cluster or network.

Auto-Scaling Node Configuration​

Once the master nodes are stable, you can dynamically launch additional Kadeck instances to scale horizontally.

Auto-scaling nodes need only one configuration:

XEOTEK_KADECK_CLUSTER_NODES=kadeck-1:2551,kadeck-2:2552,kadeck-3:2553

When an auto-scaling node comes online:

  • It contacts the master nodes.
  • Registers itself into the cluster.
  • Receives the full cluster membership list through gossiping.

There is no need to manually configure XEOTEK_KADECK_CLUSTER_HOSTNAME or XEOTEK_KADECK_CLUSTER_PORT for auto-scaling nodes; these are determined automatically at runtime.

Best Practices for Cluster Deployments​

  • Use fully qualified domain names (FQDNs) for all node references in XEOTEK_KADECK_CLUSTER_NODES.
  • Run an odd number of master nodes to optimize cluster quorum and failover (typically 3, 5, or 7).
  • Distribute master nodes across availability zones (if in a cloud environment) for maximum resilience.
  • Configure resource requests/limits properly to ensure predictable capacity.
  • Monitor cluster health through Kadeck’s /health endpoint and external monitoring systems.
  • Test node failures regularly to verify failover behavior and cluster stability.

Example Cluster Configuration Summary​

Node TypeEnvironment Variables Example
Master NodeSet XEOTEK_KADECK_CLUSTER_NODES, XEOTEK_KADECK_CLUSTER_HOSTNAME, XEOTEK_KADECK_CLUSTER_PORT
Auto-Scaling NodeSet XEOTEK_KADECK_CLUSTER_NODES only

Key Environment Variables for Cluster Mode​

VariableDescription
XEOTEK_KADECK_CLUSTER_NODESComma-separated list of all master nodes (host:port)
XEOTEK_KADECK_CLUSTER_HOSTNAMEHostname of the node (masters only)
XEOTEK_KADECK_CLUSTER_PORTPort for cluster communication (masters only)