💾 Keepalived Docker Container

A lightweight, Alpine-based Docker container for running Keepalived with VRRP (Virtual Router Redundancy Protocol) support.

✨ Features

• Alpine-based: Lightweight and secure base image
• VRRP support: High availability with Virtual Router Redundancy Protocol (VRRP)
• Easy Configuration: Configure Keepalived using environment variables, and service check-scripts
• Health Checks: Monitor service health with built-in Docker health checks

🚀 Quick Start

Run the container:

# Pull the image
docker pull peterweissdk/keepalived

# Run with custom configuration
docker run -d \
  --name keepalived \
  --restart=unless-stopped \
  --cap-add=NET_ADMIN \
  --cap-add=NET_BROADCAST \
  --cap-add=NET_RAW \
  --net=host \
  --env-file .env \
  keepalived:latest

# Run the container using the provided Docker Compose and .env file
docker compose up -d

🔧 Configuration

Environment Variables

Variable	Description	Example
TZ	Container timezone	Europe/Copenhagen
VRRP_INSTANCE	VRRP instance name	VI_1
INTERFACE	Network interface	eth0
STATE	Node state (MASTER/BACKUP)	MASTER
PRIORITY	Node priority (1-255)	100
ROUTER_ID	Unique router ID	52
VIRTUAL_IPS	Virtual IP address with subnet mask	192.168.1.100/24
UNICAST_SRC_IP	Source IP for unicast communication	192.168.1.101
UNICAST_PEERS	Peer IP addresses for unicast communication	192.168.1.102
WEIGHT	Weight for tracked scripts	50
FALL	Number of failures before transition	2
RISE	Number of successes before transition	2

Required Capabilities

• NET_ADMIN: For network interface configuration
• NET_BROADCAST: For VRRP advertisements
• NET_RAW: For raw socket access

Service Check-Script

Create a script to run at regular intervals to check the state of your service. Create a bind mount and copy the script into it

• Name of script: check-script.sh
• Bind mount point: /usr/local/scripts/
• Runs at regular intervals: 2 seconds

🏗️ Building from Source

# Clone the repository
git clone https://github.com/peterweissdk/keepalived.git
cd keepalived

# Build the image
docker build -t keepalived:latest .

📝 Directory Structure

keepalived/
├── conf/
│   └── keepalived.conf_tpl
├── scripts/
│   └── check_and_run.sh
├── .github/
├── .env
├── Dockerfile
├── docker-entrypoint.sh
├── healthcheck.sh
├── docker-compose.yml
├── LICENSE
└── README.md

🔍 Health Check

The container includes a comprehensive health check system that monitors:

1. Keepalived Process Status

   • Verifies the keepalived daemon is running

2. Virtual IP environment variable

   • Verifies the VIRTUAL_IPS environment variable is set

View health status:

docker inspect --format='{{.State.Health.Status}}' keepalived

View detailed health check history:

docker inspect --format='{{json .State.Health}}' keepalived | jq

Watch health status in real-time:

watch -n 5 'docker inspect --format="{{.State.Health.Status}}" keepalived'

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🆘 Support

If you encounter any issues or need support, please file an issue on the GitHub repository.

📄 License

This project is licensed under the GNU GENERAL PUBLIC LICENSE v3.0 - see the LICENSE file for details.