puzzle/keepalived

puzzle/keepalived

镜像概述和主要用途

puzzle/keepalived是一个用于运行Keepalived的Docker镜像。Keepalived是一款基于VRRP（虚拟路由冗余协议）的高可用解决方案，主要用于实现服务器的故障转移和虚拟IP（VIP）管理。该镜像支持通过环境变量快速配置，也可自定义配置文件，适用于构建高可用集群环境，确保服务持续可用。

获取预构建镜像的首选源为quay.io，https://hub.docker.com/r/puzzle/keepalived/%E6%BA%90%E5%B7%B2%E5%BC%83%E7%94%A8%E3%80%82

核心功能和特性

• 支持通过环境变量快速配置Keepalived核心参数（如网络接口、密码、优先级等）
• 允许挂载自定义keepalived.conf配置文件
• 提供调试模式，支持多种日志级别（none、error、warning、info、debug、trace）
• 基于osixia/light-baseimage构建，优化容器环境
• 支持扩展镜像以添加自定义证书、配置或脚本
• 提供灵活的环境变量设置方式（命令行参数、环境文件、扩展镜像）

使用场景和适用范围

• 高可用集群环境中的虚拟IP管理
• 服务器节点故障自动转移
• 需要实现服务高可用性的场景（如Web服务、数据库集群等）
• 快速部署和测试Keepalived功能

详细使用方法和配置说明

快速启动

该镜像要求主机已加载ip_vs内核模块（可通过modprobe ip_vs加载），且需使用--cap-add=NET_ADMIN和--net=host参数运行：

bash
docker run --cap-add=NET_ADMIN --net=host -d puzzle/keepalived:latest

入门指南

使用自定义Keepalived配置

镜像内置默认配置文件，可通过环境变量自定义，也可使用以下两种方式加载自定义配置：

• 运行时挂载配置文件至/container/service/keepalived/assets/keepalived.conf：

  bash
  docker run --volume /data/my-keepalived.conf:/container/service/keepalived/assets/keepalived.conf --detach puzzle/keepalived:latest
  

• 通过扩展或克隆镜像添加配置文件（详见高级用户指南）

解决Docker挂载文件问题

在部分系统中，挂载文件可能出现权限或所有权问题。启动脚本会尝试调整文件权限，可能导致错误。可通过--copy-service参数解决：

bash
docker run [你的选项] puzzle/keepalived:latest --copy-service

调试

容器默认日志级别为info，支持的级别包括：none、error、warning、info、debug、trace。

示例：以debug模式运行容器

bash
docker run --detach puzzle/keepalived:latest --loglevel debug

查看所有命令行选项：

bash
docker run puzzle/keepalived:latest --help

环境变量

环境变量默认值定义在image/environment/default.yaml，可通过以下方式自定义（详见设置环境变量）。

设置环境变量

命令行参数方式

通过--env参数设置：

bash
docker run --env KEEPALIVED_INTERFACE="eno1" --env KEEPALIVED_PASSWORD="password!" \
  --env KEEPALIVED_PRIORITY="100" --detach puzzle/keepalived:latest

链接环境文件

将环境文件挂载至/container/environment/XX-somedir（XX需小于99，确保优先于默认环境文件处理）：

bash
docker run --volume /data/environment/my-env.yaml:/container/environment/01-custom/env.yaml \
  --detach puzzle/keepalived:latest

扩展镜像

若有私有仓库，推荐通过扩展镜像设置环境变量（详见扩展镜像）。

特殊环境变量设置

对于列表类型的环境变量（如KEEPALIVED_UNICAST_PEERS），需添加#PYTHON2BASH:标签并将YAML格式转换为Python列表格式：

bash
docker run --env KEEPALIVED_UNICAST_PEERS="#PYTHON2BASH:['192.168.1.10', '192.168.1.11']" --detach puzzle/keepalived:latest

可通过在线工具将YAML转换为Python格式。

高级用户指南

Docker镜像版本控制

镜像标签分为三类：

1. latest：主分支最新提交构建，不建议生产环境使用
2. <keepalived_version>-rc.*：Keepalived新版本测试构建，仅用于测试/预发环境，标签可能被覆盖
3. <keepalived_version>：经过测试的稳定版，推荐生产环境使用，标签不会被覆盖

扩展puzzle/keepalived镜像

如需添加自定义TLS证书、配置或环境文件，建议扩展镜像。示例Dockerfile：

dockerfile
FROM puzzle/keepalived:<当前版本>
LABEL maintainer="你的姓名 <your@name.com>"

ADD keepalived.conf /container/service/keepalived/assets/keepalived.conf
ADD environment /container/environment/01-custom
ADD scripts.sh /container/service/keepalived/assets/notify.sh

测试

使用Bats（Bash自动化测试系统）进行测试：

bash
# 安装Bats后，在项目目录执行
make test

基础镜像：osixia/light-baseimage

本镜像基于osixia/light-baseimage构建，更多信息见https://github.com/osixia/docker-light-baseimage%E3%80%82

参考

感谢以下项目：

• https://github.com/osixia/docker-keepalived
• https://github.com/splattner/docker-keepalived