cobra1978/keepalived repository overview

⁠Alpine Keepalived Ultra-Light

A high-performance, ultra-lightweight Keepalived container based on Alpine Linux 3.23. This image is stripped of heavy frameworks (no Python, no Osixia-bloat) to provide a minimal footprint and maximum security.

⁠🚀 Features

• Ultra-lightweight: ~15MB total size (compared to 100MB+ for Python-based alternatives).
• Modern Engine: Built on Alpine 3.23 with Keepalived 2.4.1.
• Hybrid Configuration: Supports both automatic generation via Environment Variables and custom configuration via Volume mounting.
• Boot-Resilient: Includes race-condition protection for network interfaces and Docker Config mounts during server reboots.
• Real-time Logging: Logs and diagnostics are natively redirected to stdout/stderr for seamless integration with docker logs.
• Security & Scripting: Pre-configured with keepalived_script user to securely execute healthcheck scripts.

⁠🛠 Usage & Deployment

⁠1. Simple Mode (Environment Variables)

Perfect for standard Master/Backup setups. Configuration is generated automatically at startup.

services:
  keepalived:
    image: ghcr.io/your-username/keepalived:latest
    cap_add:
      - NET_ADMIN
      - NET_RAW
    network_mode: host # Required for VRRP
    environment:
      - STATE=MASTER
      - MYIF=eno1           # Recommended: prioritized over INTERFACE
      - VIRTUAL_IP=192.168.1.100/24
      - PRIORITY=101
      - ROUTER_ID=51

⁠2. Advanced Mode (Custom File)

If you need complex features like Unicast Peers, multiple VRRP instances, or health-check scripts, mount your own configuration.

services:
  keepalived:
    image: ghcr.io/your-username/keepalived:latest
    cap_add:
      - NET_ADMIN
      - NET_RAW
    network_mode: host
    volumes:
      - ./my-keepalived.conf:/etc/keepalived/keepalived.conf:ro

⁠Configuration Reference (Tabella per il README)

⁠⚙️ Configuration Reference

⁠🏗 Build & Automation

⁠Local Build

docker build -t my-keepalived .

⁠GitHub Actions Integration

The image is built and pushed automatically on every tag or push to main. The build process uses multi-stage builds to ensure the final image contains no build-time dependencies.

⁠Troubleshooting & Debugging

⁠View real-time logs:

docker logs -f keepalived

⁠Verify the active configuration generated by the entrypoint:

docker exec -it keepalived cat /etc/keepalived/keepalived.conf

⁠Check network status and assigned VIPs:

docker exec -it keepalived ip addr show

⁠Reboot Race Conditions

If this container starts before the network interface or the configuration mount is ready (common during server reboots), it will:

1. Wait up to 10 seconds for the configuration file to appear.
2. Wait up to 60 seconds for the network interface to be UP.
3. Log full diagnostic information (ip addr, ip route) before launching the binary.

⁠Script Execution

Healthcheck scripts are executed by the keepalived_script user for security. Ensure your scripts are readable by this user.

⁠📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⁠Maintained with ❤️ by [MarcelloPercoco]