containrrr/shepherd

Shepherd

镜像概述和主要用途

Shepherd是一个Docker Swarm服务，旨在当服务的基础镜像更新时自动更新您的Swarm服务。它通过定时检查镜像版本，触发Docker Swarm的原生更新机制，减少手动操作，确保服务始终使用最新的基础镜像，适用于需要自动维护服务更新的Swarm集群环境。

核心功能和特性

• 自动更新服务：检测到基础镜像更新时，自动触发Swarm服务更新
• 定时检查：默认每5分钟检查一次镜像更新，可通过SLEEP_TIME调整间隔
• 服务过滤控制：支持通过FILTER_SERVICES指定更新服务，或IGNORELIST_SERVICES忽略特定服务
• 失败回滚机制：设置ROLLBACK_ON_FAILURE可在更新失败时回滚到上一版本
• 私有仓库支持：支持私有仓库认证，可通过环境变量或secret文件配置多仓库认证信息
• 更新参数自定义：通过UPDATE_OPTIONS和ROLLBACK_OPTIONS控制服务更新和回滚的额外参数
• 通知集成：可与apprise微服务集成，实现服务更新通知
• 镜像自动清理：设置IMAGE_AUTOCLEAN_LIMIT可自动清理旧镜像
• 单次运行模式：支持RUN_ONCE_AND_EXIT单次检查后退出，适合与cron调度工具配合使用

使用场景和适用范围

• Docker Swarm集群中需要自动维护服务更新的场景
• CI/CD流程中，基础镜像构建完成后自动部署到Swarm服务
• 需要定时检查并更新服务以保持基础镜像最新的环境
• 希望减少手动执行docker service update操作的运维场景
• 需要对服务更新进行精细化控制（如指定更新间隔、忽略特定服务、配置回滚策略）的环境

使用方法和配置说明

基本部署方式

使用docker service create部署

shell
docker service create --name shepherd \
                      --constraint "node.role==manager" \
                      --mount type=bind,source=/var/run/docker.sock,target=/var/run/docker.sock,ro \
                      containrrr/shepherd

使用Docker Compose部署

yaml
version: "3"
services:
  shepherd:
    image: containrrr/shepherd
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    deploy:
      placement:
        constraints:
          - node.role == manager

更多示例配置可参考项目中的docker-compose.yml和examples文件夹。

配置参数详解

Shepherd通过环境变量进行配置，主要参数如下：

高级配置示例

带环境变量的完整部署示例

shell
docker service create --name shepherd \
                      --constraint "node.role==manager" \
                      --env SLEEP_TIME="5m" \
                      --env IGNORELIST_SERVICES="shepherd my-other-service" \
                      --env WITH_REGISTRY_AUTH="true" \
                      --env WITH_INSECURE_REGISTRY="true" \
                      --env WITH_NO_RESOLVE_IMAGE="true" \
                      --env FILTER_SERVICES="label=com.mydomain.autodeploy" \
                      --env APPRISE_SIDECAR_URL="apprise-microservice:5000" \
                      --env IMAGE_AUTOCLEAN_LIMIT="5" \
                      --env RUN_ONCE_AND_EXIT="true" \
                      --env ROLLBACK_ON_FAILURE="true" \
                      --env UPDATE_OPTIONS="--update-delay=30s" \
                      --env TZ=Europe/Berlin \
                      --mount type=bind,source=/var/run/docker.sock,target=/var/run/docker.sock,ro \
                      --mount type=bind,source=/root/.docker/config.json,target=/root/.docker/config.json,ro \
                      containrrr/shepherd

注意：上述命令中的引号由shell解析，不属于环境变量值的一部分。

多私有仓库认证配置

1. 创建认证信息文件（制表符分隔，包含id、registry、login、password）：

   blog	registry.gitlab.com	gitlab+deploy-token-5123674	ssw2Nrd2
   

2. 创建Docker secret：

   shell
   docker secret create shepherd-registries-auth private/shepherd-registries-auth
   

3. 在Docker Compose中配置Shepherd：

   yaml
   services:
     shepherd:
       image: containrrr/shepherd
       environment:
         REGISTRIES_FILE: /var/run/secrets/shepherd-registries-auth
       secrets:
         - shepherd-registries-auth
       deploy:
         placement:
           constraints:
             - node.role == manager
   secrets:
     shepherd-registries-auth:
       external: true
   

4. 在目标服务上添加标签指定认证id：

   yaml
   deploy:
     labels:
       - shepherd.enable=true
       - shepherd.auth.config=blog
   

运行在cron调度上

使用默认SLEEP_TIME时运行时间会漂移，如需固定调度，建议与https://github.com/crazy-max/swarm-cronjob%E9%85%8D%E5%90%88%EF%BC%9A

1. 按照swarm-cronjob文档创建cron服务。
2. 配置Shepherd：
   • 设置RUN_ONCE_AND_EXIT=true
   • replicas=0
   • restart_policy: condition: none
   • 添加swarm-cronjob调度标签

示例配置可参考docker-compose.swarm-cronjob.yml。

工作原理

Shepherd通过更新服务的镜像规范（移除当前摘要）触发更新。Docker会自动处理：

1. 解析镜像标签并检查仓库中的最新版本
2. 根据Swarm服务配置执行滚动更新（如副本数、更新延迟等）
3. 维护服务可用性，对于复制服务通常无明显downtime

大部分更新逻辑依赖Docker原生功能，Shepherd主要负责定时触发检查和更新操作。