keepalived

packaged by Chainguard

Chainguard Container for keepalived

Keepalived implements the Virtual Router Redundancy Protocol (VRRP) so a virtual IP can fail over between routers, and drives the Linux Virtual Server (IPVS) kernel load balancer with health checkers that add and remove real servers as they come and go.

Chainguard Containers are regularly-updated, secure-by-default container images.

Download this Container Image

For those with access, this container image is available on cgr.dev:

docker pull cgr.dev/ORGANIZATION/keepalived:latest

Be sure to replace the ORGANIZATION placeholder with the name used for your organization's private repository within the Chainguard Registry.

Compatibility Notes

The keepalived project does not publish a container image, so there is no upstream image to be a drop-in replacement for. Upstream ships a Dockerfile.in template in its source tree that users build themselves, and this image follows it: the entrypoint is the same, and the binary is reachable at both /usr/sbin/keepalived and /usr/bin/keepalived.

One deliberate difference: no configuration file ships in the image. Upstream's Dockerfile copies a demo keepalived.conf that claims the address 10.247.254.2 on eth0. Since nothing else advertises for that virtual router, a container started with it wins the election and takes that address on whatever network it joins. Mount your own configuration instead, as described below. This also matches upstream's own make install, which stopped installing a default keepalived.conf after v2.2.4 and ships only keepalived.conf.sample.

A commented reference configuration is included at /etc/keepalived/keepalived.conf.sample.

This image runs as root. VRRP assigns virtual IPs and the health checkers program IPVS, both of which require CAP_NET_ADMIN, so keepalived cannot run as an unprivileged user.

Prerequisites

keepalived manages addresses and routes on a real network interface, so the container needs:

• CAP_NET_ADMIN and CAP_NET_RAW,
• a writable /run: keepalived writes keepalived.pid, keepalived_vrrp.pid and keepalived_checkers.pid there. Under a read-only root filesystem, mount a writable volume at /run, or the pid-file open fails and keepalived reports it as daemon is already running, and
• an interface it can act on. In practice that means host networking, or a network the container shares with the peers it fails over with. Set interface to that host's actual NIC name: keepalived exits if the interface does not exist, and it is often not eth0.

VRRP uses IP protocol 112 to the multicast group 224.0.0.18 rather than a TCP port, so no ports are published. Where multicast is unavailable, configure unicast_peer instead.

Getting Started

Write a configuration and mount it over /etc/keepalived/keepalived.conf. This example makes the container the VRRP master for a virtual IP on eth0; with --network host that is the host's interface name, so substitute your own everywhere eth0 appears below:

cat > keepalived.conf <<'EOF'
global_defs {
    router_id node1
}

vrrp_instance VI_1 {
    state BACKUP
    interface eth0
    virtual_router_id 51
    priority 100
    advert_int 1
    virtual_ipaddress {
        192.0.2.100/32 dev eth0
    }
}
EOF

docker run -d --name keepalived \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  --network host \
  -v "$PWD/keepalived.conf:/etc/keepalived/keepalived.conf:ro" \
  cgr.dev/ORGANIZATION/keepalived:latest

With no peer advertising a higher priority, the instance is promoted after the advertisement interval:

docker logs keepalived 2>&1 | grep "Entering MASTER STATE"

and the virtual IP is assigned to the interface:

docker exec keepalived ip -4 addr show dev eth0

Bring up a second node with a lower priority and the same virtual_router_id to see the address move when the master stops.

Before starting the daemon, you can check a configuration without running it:

docker run --rm --entrypoint /usr/bin/keepalived \
  -v "$PWD/keepalived.conf:/etc/keepalived/keepalived.conf:ro" \
  cgr.dev/ORGANIZATION/keepalived:latest --config-test

Configuration

keepalived itself is configured entirely through /etc/keepalived/keepalived.conf; it reads no environment variables of its own. The image does honour CHAINGUARD_LEGACY_ALLOWED=0, which deactivates OpenSSL's legacy provider and so disables the MD5 used by auth_type AH and by the url { digest } checker option. The entrypoint runs the daemon in the foreground with --dont-fork --log-console, so it logs to stderr rather than to a file inside the container. docker logs shows it; pipe with 2>&1 when grepping.

Health checkers are the other half of a typical configuration. IPVS is a kernel facility, so the ip_vs module must already be loaded on the host: the image ships no modprobe, and without it keepalived logs IPVS: Can't initialize ipvs and silently stops load balancing.

This virtual_server load balances two backends and removes one automatically when its HTTP check fails:

virtual_server 192.0.2.100 80 {
    delay_loop 5
    lb_algo rr
    lb_kind NAT
    protocol TCP

    real_server 192.0.2.11 80 {
        weight 1
        HTTP_GET {
            url { path /healthz status_code 200 }
            connect_timeout 2
        }
    }

    real_server 192.0.2.12 80 {
        weight 1
        HTTP_GET {
            url { path /healthz status_code 200 }
            connect_timeout 2
        }
    }
}

To pin a checker to a response body rather than a status code, compute the digest with the genhash tool the image also ships:

docker run --rm --entrypoint /usr/bin/genhash \
  cgr.dev/ORGANIZATION/keepalived:latest -s 192.0.2.11 -p 80 -u /healthz

If you use notify or vrrp_script hooks, keepalived runs them as the keepalived_script user, which this image creates. Scripts must be readable and executable by that user, and every directory in the path to the script must be owned by root and not writable by anyone else, or enable_script_security refuses to run them.

This image ships no shell or interpreter, so a hook must be an executable the kernel can run directly -- a dynamically linked ELF binary is fine, as long as its libraries are in the image. A #!/bin/sh script fails to exec, and a command written as a shell string is run through system(), which also needs a shell. Add busybox with Custom Assembly if your hooks need one.

keepalived's parent process stays alive if the VRRP child exits transiently, so a container can look healthy while doing nothing. It does exit on a configuration error, a fatal error or a missing permission, so container liveness catches those. For everything else, watch for Entering MASTER STATE or poll the virtual IP rather than relying on container liveness alone.

This image is built with VRRP, LVS/IPVS, BFD, nftables, iptables, ipset, SNMP (including the RFC VRRP MIBs), DBus, JSON and regex support compiled in. SNMP is an AgentX subagent, so it needs a master agent reachable at /var/agentx/master; neither that socket nor its directory exists in the image, so mount the socket in from a master agent on the host. Run docker run --rm --entrypoint /usr/bin/keepalived cgr.dev/ORGANIZATION/keepalived:latest -v to print the full list.

Documentation and Resources

• keepalived user guide
• keepalived.conf reference
• Upstream source

What are Chainguard Containers?

Chainguard's free tier of Starter container images are built with Wolfi, our minimal Linux undistro.

All other Chainguard Containers are built with Chainguard OS, Chainguard's minimal Linux operating system designed to produce container images that meet the requirements of a more secure software supply chain.

The main features of Chainguard Containers include:

• Minimal design, without unnecessary software bloat
• Daily builds to ensure container images are up-to-date with available security patches
• High quality build-time SBOMs attesting to the provenance of all artifacts within the image
• Verifiable signatures provided by Sigstore
• Reproducible builds with Cosign and apko (read more about reproducibility)

For cases where you need container images with shells and package managers to build or debug, most Chainguard Containers come paired with a development, or -dev, variant.

In all other cases, including Chainguard Containers tagged as :latest or with a specific version number, the container images include only an open-source application and its runtime dependencies. These minimal container images typically do not contain a shell or package manager.

Although the -dev container image variants have similar security features as their more minimal versions, they include additional software that is typically not necessary in production environments. We recommend using multi-stage builds to copy artifacts from the -dev variant into a more minimal production image.

Need additional packages?

To improve security, Chainguard Containers include only essential dependencies. Need more packages? Chainguard customers can use Custom Assembly to add packages, either through the Console, chainctl, or API.

To use Custom Assembly in the Chainguard Console: navigate to the image you'd like to customize in your Organization's list of images, and click on the Customize image button at the top of the page.

Learn More

Refer to our Chainguard Containers documentation on Chainguard Academy. Chainguard also offers VMs and Libraries — contact us for access.

Trademarks

This software listing is packaged by Chainguard. The trademarks set forth in this offering are owned by their respective companies, and use of them does not imply any affiliation, sponsorship, or endorsement by such companies.