rancher/configmap-reload 镜像文档

一、镜像概述和主要用途

概述

rancher/configmap-reload 是 docker.io/jimmidyson/configmap-reload 的自动化镜像镜像，由 Rancher 镜像项目（[***] configmap-reload 工具的获取和使用。

主要用途

用于在 Kubernetes 环境中监控 ConfigMap/Secret 资源的变更，当配置发生更新时，自动触发关联应用的配置重载流程（如发送信号、调用 WebHook 等），实现应用配置的动态更新，无需重启容器。

二、核心功能和特性

1. 配置变更监控
   实时监控挂载到容器内的 ConfigMap/Secret 文件变化（通过监听文件系统事件或定期轮询）。

2. 灵活的重载触发机制
   支持多种重载方式：

   • 向目标进程发送指定信号（如 SIGHUP，常用于 Nginx、Prometheus 等服务）；
   • 调用自定义 WebHook URL（通过 HTTP 请求通知应用主动重载配置）。

3. 轻量级设计
   基于极小的基础镜像构建，资源占用低，适合作为 Sidecar 容器与主应用协同工作。

4. Kubernetes 原生支持
   无缝集成 Kubernetes 环境，可通过环境变量、命令行参数灵活配置监控路径和重载策略。

三、使用场景和适用范围

适用场景

• 动态配置更新需求的应用：如 Nginx、Envoy、Prometheus、Alertmanager 等需要热加载配置的服务。
• Kubernetes Sidecar 模式：作为 Sidecar 容器与主应用部署在同一 Pod 中，监控共享 Volume 中的 ConfigMap/Secret 变更。
• 避免应用重启：通过重载配置而非重启容器，减少服务中断时间（尤其适用于有状态应用）。

典型应用示例

• Nginx 反向代理：监控 ConfigMap 中的路由配置变更，触发 nginx -s reload。
• Prometheus 监控：监控告警规则或 scrape 配置变更，通过 SIGHUP 信号重载配置。

四、详细的使用方法和配置说明

4.1 基本使用条件

• 容器需挂载包含 ConfigMap/Secret 的 Volume（通常通过 Kubernetes volumeMounts 实现）。
• 需明确配置监控路径（ConfigMap/Secret 挂载目录）和重载触发方式。

4.2 Docker 命令行使用示例

bash
# 示例：监控 /etc/config 目录，当文件变化时向 PID 1 进程发送 SIGHUP 信号
docker run -d \
  -v /path/to/local/config:/etc/config \  # 挂载 ConfigMap 目录（本地模拟）
  rancher/configmap-reload \
  --volume-dir=/etc/config \             # 指定监控的目录（容器内路径）
  --signal=SIGHUP \                      # 发送 SIGHUP 信号
  --pid-file=/var/run/app.pid            # 目标进程 PID 文件路径（若需指定进程）

4.3 Kubernetes 部署示例（Sidecar 模式）

场景：Nginx 配置热加载

部署 Nginx 主容器 + configmap-reload Sidecar 容器，监控 ConfigMap 变更并触发 nginx -s reload。

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-with-configmap-reload
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:alpine
        volumeMounts:
        - name: nginx-config
          mountPath: /etc/nginx/conf.d  # 挂载 ConfigMap 到 Nginx 配置目录
        ports:
        - containerPort: 80
      - name: configmap-reload  # Sidecar 容器
        image: rancher/configmap-reload
        args:
        - --volume-dir=/etc/config  # 监控的目录（与主容器共享的 Volume 路径）
        - --webhook-url=http://localhost:8080/reload  # 调用 Nginx 自定义 reload 接口（若有）
        # 或使用信号重载：--signal=SIGHUP --pid-file=/var/run/nginx.pid
        volumeMounts:
        - name: nginx-config
          mountPath: /etc/config  # 挂载同一 ConfigMap Volume
      volumes:
      - name: nginx-config
        configMap:
          name: nginx-conf  # 关联的 ConfigMap 名称

4.4 Kubernetes DaemonSet 部署（节点级监控）

如需在所有节点监控特定 ConfigMap，可通过 DaemonSet 部署：

yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: configmap-reload-daemon
spec:
  selector:
    matchLabels:
      app: configmap-reload
  template:
    metadata:
      labels:
        app: configmap-reload
    spec:
      containers:
      - name: configmap-reload
        image: rancher/configmap-reload
        args:
        - --volume-dir=/etc/node-config  # 节点级配置目录
        - --signal=SIGHUP
        - --pid-file=/var/run/node-agent.pid
        volumeMounts:
        - name: node-config
          mountPath: /etc/node-config
      volumes:
      - name: node-config
        hostPath:
          path: /etc/node-config  # 节点主机路径（需提前挂载 ConfigMap 到该路径）

五、配置参数说明

命令行参数

环境变量

无特殊环境变量，所有配置通过命令行参数指定。

六、注意事项

1. 与原镜像一致性
   本镜像为 jimmidyson/configmap-reload 的镜像，功能、参数与原镜像完全一致。详细使用说明可参考原镜像文档：[***]

2. 文件系统权限
   确保容器对挂载的 --volume-dir 目录有读权限，否则可能无法检测到文件变更。

3. 重载逻辑依赖
   应用需支持通过信号或 WebHook 触发配置重载（如 Nginx 支持 SIGHUP，Prometheus 支持 /reload 端点）。

4. Rancher 镜像维护
   镜像同步状态可通过 Rancher 镜像项目查看：[***]

七、参考链接

• 原镜像项目：jimmidyson/configmap-reload
• Rancher 镜像项目：rancher/image-mirror
• Kubernetes ConfigMap 文档：Configure a Pod to Use a ConfigMap