cplieger/docker-keepalived repository overview

⁠docker-keepalived

docker-keepalived runs keepalived⁠ in a container, so two or more Linux hosts share a virtual IP address that moves to a healthy host when one fails. You write the keepalived.conf. The image does not generate one from settings.

⁠What it does

docker-keepalived keeps one address reachable while a host, or a service on it, goes down.

• Moves the virtual IP to another host within seconds when the host holding it stops sending adverts.
• Moves it when a check script you write reports that your service is down.
• Rereads a changed keepalived.conf on a reload signal, without restarting the container.
• Reports every failover and failed check in docker logs, with 11 Loki alert rules ready to load.

⁠Who it is for

docker-keepalived is built for admins who already write keepalived configurations and want keepalived in a container. It runs a pinned official keepalived release, patched so a check script that cannot start shows in the log.

You need two or more Linux hosts with Docker on one network, on amd64 or arm64. The container runs as root with host networking and the NET_ADMIN and NET_RAW capabilities.

Three other options suit other setups:

• Consider your distribution's keepalived package to run it on the host itself, which its maintainers call the quickest install.
• Consider osixia/keepalived⁠ if you want the configuration generated from environment variables.
• Consider kube-vip⁠ if you want a virtual IP for a Kubernetes control plane or LoadBalancer services.

docker-keepalived is free software under the Apache-2.0 license. keepalived itself is under GPL-2.0-or-later.

⁠Pull

docker pull cplieger/docker-keepalived:latest

Also published to ghcr.io/cplieger/docker-keepalived with identical images and tags. Release versions are tagged vX.Y.Z alongside latest.

⁠Quick start

# Example compose for docker-keepalived. See docs/configuration.md and docs/hardening.md for all configuration options and hardening.
services:
  keepalived:
    image: ghcr.io/cplieger/docker-keepalived:latest
    container_name: keepalived
    restart: unless-stopped

    # VRRP sends multicast adverts on your LAN, so it needs host networking and these two capabilities.
    network_mode: host
    cap_add:
      - NET_ADMIN
      - NET_RAW

    # Put keepalived.conf in ./keepalived and your scripts in ./keepalived/scripts before the first start.
    # Give the folder to root and let only root write to it, or keepalived disables your scripts.
    volumes:
      - "./keepalived:/etc/keepalived:ro"

⁠Documentation

• Full documentation⁠ — configuration, behavior, security
• Configuration⁠
• Security⁠
• How docker-keepalived works⁠
• Monitoring and alerts⁠
• Contributing⁠
• Releases and changelog⁠

⁠License

Apache-2.0. See LICENSE⁠. The image carries the license text of every bundled component under /usr/share/licenses/. The Alpine packages in the image ship no license file upstream, so their license texts are kept under licenses/ in this repository and copied in.

The bundled component is keepalived itself, which is GPL-2.0-or-later. The build fetches the pinned release tarball https://www.keepalived.org/software/keepalived-<version>.tar.gz, at the version the KEEPALIVED_VERSION argument in the Dockerfile⁠ pins without its leading v, verifies the pinned SHA256, and applies the checked-in patch below. keepalived's own COPYING travels in the image at /usr/share/licenses/keepalived/COPYING, and the upstream project is acassen/keepalived⁠. That tarball, this repository's Dockerfile and the patch are the complete recipe for the keepalived binary in the image, which is how anyone who receives it gets the corresponding source.

The patch changes keepalived's own source, so it stays GPL-2.0-or-later:

• patches/0001-report-a-script-that-could-not-be-executed.patch⁠ is a local change with no upstream commit behind it.