How pkolano/ballast works
Project Type and Purpose
• Ballast is a specialized framework designed to balance SSH load by dynamically redirecting SSH connections within a bastion architecture.
• The README explains that the system is composed of three main parts: a Ballast agent (running on each “balanced” host), a Ballast server (aggregating load information and making balancing decisions), and a Ballast client (invoked by SSH on bastions and internal hosts to resolve host aliases).
• The project includes components in both C (in the c/ directory) and Perl (in the perl/ directory), in addition to Debian packaging files and documentation.
File Structure
• Top-level directories:
– c/: Contains C source files (e.g., ballast.c) component which might implement low‐level or performance-critical parts.
– perl/: Contains scripts for ballast, ballast-agent, and ballastd, indicating that parts of the system (likely the agent, server, or client wrappers) are implemented in Perl.
– debian/: Packaging files for preparing Ballast for Debian distributions.
– doc/: Contains manual pages and documentation that detail usage and configuration.
– etc/: Provides default configuration files (e.g., ballastrc) and systemd service units, which give insight into how the system is deployed and controlled.
• The presence of systemd service definitions in etc/systemd indicates that Ballast components (the agent, server, and/or possibly a timer for the agent) are managed as services.
a. Primary Components:
– Ballast Agent: Deployed on every balanced (internal) host. It periodically gathers load information and sends it to the Ballast server. (Referenced in perl/ballast-agent and the systemd unit file ballast-agent.service.)
– Ballast Server: Aggregates load data from all agents and decides which host should be used when a balancing decision is invoked. (Appears related to ballastd as per perl/ballastd and the man page doc/ballastd.1.)
– Ballast Client: Runs on bastion and internal hosts to intercept SSH connections. It contacts the Ballast server to resolve host aliases into actual hostnames. (See perl/ballast and the documentation in doc/ballast.1.)
– TCP Relay/External Utilities: The server returns the chosen host, and then a built-in TCP relay (or something like netcat) facilitates the connection.
b. Relationships & Data Flow:
– Load Monitoring Flow: Each Ballast Agent (on balanced hosts) collects system load metrics → Sends data to the Ballast Server.
– Connection/Load Balancing Flow: A user initiates an SSH connection using a balancing alias → The Ballast Client is triggered → It contacts the Ballast Server → The server uses the aggregated load data (and user-specific policies) to select one (or more) host(s) → The client initiates a connection via a TCP relay to the chosen host.
c. Architectural Patterns and Design Principles:
– Distributed Load Monitoring: A decentralized approach where each host provides its own performance data.
– Centralized Decision Making: A resilient, central Ballast Server aggregates metrics and makes dynamic routing decisions.
– Client-Side Integration: Transparent integration with SSH, leveraging existing client aliasing/proxying capabilities without modifying external access patterns.
d. Technologies, Frameworks, and Libraries:
– C and Perl are used for performance-critical components and higher-level glue scripts.
– systemd service unit files indicate that process supervision and scheduling are managed via systemd.
– TCP relay mechanisms and possibly utilities like netcat are used to establish final SSH connections.