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 Portal instances

Overview of Cluster Architecture​

A Portal 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
Portal-1portal-12551
Portal-2portal-22552
Portal-3portal-32553

All master nodes must know about each other.

2. Configure Each Master Node​

Set the following environment variables on each master:

Example: Portal-1​

XTK_KADECK_CLUSTER_NODES=portal-1:2551,portal-2:2552,portal-3:2553
XTK_KADECK_CLUSTER_HOSTNAME=portal-1
XTK_KADECK_CLUSTER_PORT=2551

Example: Portal-2​

XTK_KADECK_CLUSTER_NODES=portal-1:2551,portal-2:2552,portal-3:2553
XTK_KADECK_CLUSTER_HOSTNAME=portal-2
XTK_KADECK_CLUSTER_PORT=2552

Example: Portal-3​

XTK_KADECK_CLUSTER_NODES=portal-1:2551,portal-2:2552,portal-3:2553
XTK_KADECK_CLUSTER_HOSTNAME=portal-3
XTK_KADECK_CLUSTER_PORT=2553

Important:
All masters must list the same XTK_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 Portal instances to scale horizontally.

Auto-scaling nodes need only one configuration:

XTK_KADECK_CLUSTER_NODES=portal-1:2551,portal-2:2552,portal-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 XTK_KADECK_CLUSTER_HOSTNAME or XTK_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 XTK_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 Portal’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 XTK_KADECK_CLUSTER_NODES, XTK_KADECK_CLUSTER_HOSTNAME, XTK_KADECK_CLUSTER_PORT
Auto-Scaling NodeSet XTK_KADECK_CLUSTER_NODES only

Key Environment Variables for Cluster Mode​

VariableDescription
XTK_KADECK_CLUSTER_NODESComma-separated list of all master nodes (host:port)
XTK_KADECK_CLUSTER_HOSTNAMEHostname of the node (masters only)
XTK_KADECK_CLUSTER_PORTPort for cluster communication (masters only)