KeepAliveD-Generator/README.md

# KeepAliveD-Generator

This project is a **Bash-based automation tool** for generating a complete High Availability (HA) setup using Keepalived VRRP. It supports multiple backup nodes, multiple VIP instances, Systemd service creation, and automatic topology diagram generation.

---

# Overview

The script interactively builds a full HA stack for a generic service (DNS, API, load balancer, etc.) by generating:

- Keepalived configuration files (MASTER + multiple BACKUP nodes)
- Systemd service unit file
- A Mermaid-based HA topology diagram

It is designed to reduce manual configuration errors and speed up HA deployments.

---

# Features

## Keepalived Configuration Generator
- Generates VRRP instances for multiple VIPs/services
- Supports 1 MASTER + N BACKUP nodes
- Uses unicast VRRP for compatibility across routed networks
- Optional health-check script integration
- Automatic priority assignment for backups

---

## Systemd Integration
- Creates a ready-to-use `keepalived.service`
- Enables auto-start on boot
- Ensures service restart on failure

---

## Architecture Diagram Generator
- Produces a Mermaid diagram (`.md`)
- Visualizes:
  - MASTER node
  - BACKUP nodes
  - VIP failover flow
- Compatible with GitHub, Obsidian, and Mermaid Live Editor

---

# Supported Use Cases

This generator is **service-agnostic** and can be used for:

- DNS failover (AdGuard, Unbound, Bind)
- Reverse proxies (Nginx, HAProxy)
- APIs and microservices
- Database VIP failover (MySQL, PostgreSQL)
- Any Linux-based floating IP service

---

# Requirements

- Linux system (Debian/Ubuntu recommended)
- Bash shell
- Keepalived installed (`keepalived`)
- Root or sudo access

Install Keepalived:

```
sudo apt update
sudo apt install keepalived -y
```

# Usage

* 1. Make script executable
```
chmod +x generate-keepalived.sh
```
* 2. Run the generator
```
./generate-keepalived.sh
```
What You Will Be Asked

The script interactively prompts for:

- Service name
- MASTER node details
- Number of BACKUP nodes
- BACKUP node IPs and IDs
- Number of VIP instances
- Interface names
- VIP addresses
- VRRP IDs
- Authentication passwords
- Optional health-check script

# Output Files

After execution, the script generates:

Keepalived configs
* keepalived-<service>-<master>.conf
* keepalived-<service>-backupX.conf
 
Systemd service
* systemd-<service>/keepalived.service

Diagram
* <service>-ha-diagram.md

# Example Architecture
```
Clients
   │
   ▼
Virtual IP (VIP)
   │
 ┌───────────────┐
 │ MASTER NODE   │
 │ BACKUP NODE 1 │
 │ BACKUP NODE 2 │
 └───────────────┘
```
# Health Check (Optional)

If enabled, the script integrates a custom health check:

Used to detect service failure
* Automatically reduces VRRP priority
Triggers failover to backup nodes

# Notes
* VRRP uses unicast mode (no multicast dependency)
* Each VIP instance must have a unique VRID
* BACKUP priorities are automatically reduced per node
* Designed for simplicity, scalability, and repeatability

Limitations
* Does not automatically install Keepalived
* Does not configure network interfaces (VLANs must exist beforehand)
* Requires manual deployment of generated files

# Future Enhancements

Planned or possible upgrades:

* YAML-based configuration input
* Ansible automation support
* Firewall rule generation (VRRP + unicast)
* Prometheus monitoring integration
* Kubernetes-style VIP abstraction layer

# License

This script is intended for internal infrastructure automation and can be adapted freely.

# Disclaimer

This tool is provided for **infrastructure automation and educational purposes only**.

It generates configuration files for Keepalived VRRP, Systemd services, and network high-availability setups based on user input. While it is designed to reduce manual configuration errors, it does not guarantee correctness, security, or suitability for any specific production environment.

## Responsibility

- You are solely responsible for reviewing, testing, and validating all generated configurations before deployment.
- Incorrect network or VRRP configurations may result in service downtime, split-brain scenarios, or network instability.
- Always test in a **staging or lab environment** before applying to production systems.

## No Warranty

This software is provided **“as is”**, without warranty of any kind, express or implied, including but not limited to:

- Fitness for a particular purpose
- Merchantability
- Non-infringement
- Availability or reliability in production environments

## Network & Security Considerations

- VRRP configurations affect network routing and failover behavior.
- Misconfigured priorities, IPs, or authentication values may lead to unintended failovers.
- Health-check scripts executed via Keepalived run with elevated privileges and should be carefully reviewed.

## Liability

The author(s) of this tool are not liable for any damages, outages, data loss, or security incidents resulting from its use or misuse.

## Recommended Practice

- Always review generated configuration files before deployment.
- Use version control (e.g., Git) to track changes.
- Validate configurations in a controlled environment before production rollout.
- Monitor systems after deployment to ensure expected failover behavior.