ghcr.io/stakater/reloader:merge-1232

📢 Reloader v2 正式发布

基于 https://sdk.operatorframework.io/ 重构的 Reloader v2 现已正式发布，所有新功能开发均在 https://github.com/stakater/Reloader/tree/v2 分支进行。

master 分支（对应 Reloader v1）已停止新功能开发，仅接收安全修复与关键 Bug 补丁。所有新功能需求和 Pull Request 请提交至 v2 分支，分支命名与 PR 标题规则请参考贡献指南。

🔁 Reloader 是什么？

Reloader 是一款 Kubernetes 控制器，当被关联的 Secret、ConfigMap 或可选的 CSI 挂载 Secret 发生更新时，它会自动触发对应工作负载（如 Deployment、StatefulSet 等）的滚动更新。

在传统 Kubernetes 部署场景中，更新 Secret 或 ConfigMap 不会自动重启或重新部署关联工作负载，这可能导致生产环境运行过期配置，尤其是凭证、功能开关、环境配置这类动态值的场景下问题更为突出。

Reloader 解决了这一痛点，可确保工作负载自动、安全地同步配置变更。

📚 完整文档请访问 Stakater 官方文档站点

🚀 为什么选择 Reloader？

• ✅ 无需手动重启：配置或 Secret 变更后，无需手动触发工作负载滚动更新
• 🔒 原生安全设计：确保应用始终使用最新的凭证或令牌
• 🛠️ 高度灵活：兼容所有主流工作负载类型，包括 Deployment、StatefulSet、Daemonset、ArgoRollout 等
• ⚡ 快速反馈闭环：完美适配 Secret/配置变更频繁的 CI/CD 流水线
• 🔄 开箱即用集成：只需为工作负载添加对应标签，剩余操作全部由 Reloader 自动完成

🔧 工作原理

flowchart LR
ExternalSecret -->|Creates| Secret
SealedSecret -->|Creates| Secret
Certificate -->|Creates| Secret
Secret -->|Watched by| Reloader
ConfigMap -->|Watched by| Reloader

Reloader -->|Triggers Rollout| Deployment
Reloader -->|Triggers Rollout| DeploymentConfig
Reloader -->|Triggers Rollout| Daemonset
Reloader -->|Triggers Rollout| Statefulset
Reloader -->|Triggers Rollout| ArgoRollout
Reloader -->|Triggers Job| CronJob
Reloader -->|Sends Notification| Slack,Teams,Webhook

• ExternalSecret、SealedSecret 或 cert-manager 提供的 Certificate 这类组件可以创建或管理 Kubernetes Secret，Secret 也支持手动创建或通过 GitOps 工作流交付
• Reloader 会持续监听所有关联 Secret 和 ConfigMap 的变更
• 检测到配置变更后，Reloader 会自动触发关联工作负载的滚动更新，确保应用始终运行最新配置

🏢 Reloader 企业版

开源版 Reloader 完全免费，已在生产环境经过验证，累计下载量超过 240 亿次。

针对有更高合规与服务要求的团队，Reloader 提供企业版选项：

→ 如有 Reloader 企业版相关需求，请联系销售团队获取详情。

⚡ 快速入门

1. 安装 Reloader

请任选一种安装方式完成部署。

2. 为工作负载添加注解

以下示例为 Deployment 启用自动重载能力：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  annotations:
    reloader.stakater.com/auto: "true"
spec:
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: app
        image: your-image
        envFrom:
        - configMapRef:
            name: my-config
        - secretRef:
            name: my-secret

该配置会告知 Reloader 监听此 Deployment 中引用的 ConfigMap 和 Secret，任意一项发生更新时都会触发工作负载滚动更新。

🧩 使用方式

Reloader 支持多种基于注解的控制规则，你可以自定义 Kubernetes 工作负载在 Secret/ConfigMap 变更时的重载时机与行为。

Kubernetes 本身不会在关联的 Secret 或 ConfigMap 更新时触发 Pod 重启，Reloader 通过监听变更自动执行滚动更新填补了这一空白，同时提供基于注解的全量控制能力，支持以下场景：

• 默认重载所有资源
• 仅针对 Secret 或仅针对 ConfigMap 启用重载
• 仅监听指定资源
• 通过标签组合（search + match）实现按需启用重载
• 排除指定不需要重载的工作负载

1. 🔁 自动重载（默认模式）

使用以下注解可在关联的 Secret 或 ConfigMap 发生变更时自动重启工作负载。

2. 📛 指定命名资源重载（自定义资源注解）

这类注解允许你手动定义可触发重载的 ConfigMap 或 Secret 名称，无需依赖这些资源是否在 Pod 配置中被引用。

适用场景

1. ✅ 适用于配置资源共享、但重载逻辑仅在特定场景下生效的精准控制场景
2. ✅ 当你明确知晓需要监听的资源范围，希望完全跳过自动发现、避免不必要的检索操作时可使用该模式

3. 🎯 定向重载（Match + Search 注解组合模式）

该模式可实现细粒度的重载控制：只有当满足以下两个条件时，工作负载才会在 Secret/ConfigMap 变更时重启：

1. 该 Secret/ConfigMap 已被工作负载引用
2. 该 Secret/ConfigMap 已显式标记 match: true 注解

工作逻辑

1. 工作负载需添加注解：reloader.stakater.com/search: "true"
2. 需要被监听的 ConfigMap 或 Secret 需添加注解：reloader.stakater.com/match: "true"
3. 该 ConfigMap 或 Secret 还需要通过环境变量、volumeMount 等方式在对应工作负载中被引用

适用场景

1. ✅ 仅当工作负载引用了显式标记 reloader.stakater.com/match: "true" 的 ConfigMap 或 Secret 时，才触发重载。
2. ✅ 适用于你希望完全控制哪些共享或系统级资源可以触发重载的场景，在多租户集群或共享配置环境中效果极佳。

⛔ 资源级忽略注解

如果需要阻止指定 ConfigMap 或 Secret 触发任何重载操作，可以直接在该资源上添加忽略注解：

apiVersion: v1
kind: ConfigMap # 也可设置为 Secret
metadata:
  name: my-config
  annotations:
    reloader.stakater.com/ignore: "true"

该配置会指示 Reloader 跳过所有工作负载对该资源的全部重载逻辑。

4. ⚙️ 工作负载专属发布策略（仅适用于 Argo Rollouts）

[!NOTE] 该功能仅在搭配 https://argoproj.github.io/argo-rollouts/ 使用时生效，不适用于标准 Kubernetes Deployment、StatefulSet 或 DaemonSet。使用前必须在 Reloader 中开启 Argo Rollouts 支持，例如通过启动参数 --is-argo-rollouts=true 启用。

默认情况下，Reloader 会通过更新 Pod 模板触发 Argo Rollouts 控制器执行标准发布流程。该逻辑在大多数场景下都能正常工作，但由于此操作会修改工作负载规约，ArgoCD 等 GitOps 工具会将其识别为「配置漂移」，并标记应用处于 OutOfSync 状态。

为避免该问题，你可以切换到 restart 策略：该策略仅重启 Pod，不会修改 Pod 模板。

metadata:
  annotations:
    reloader.stakater.com/rollout-strategy: "restart"

符合以下任意场景时，推荐使用 restart 策略：

1. 你正在使用 GitOps 工作流，希望避免出现配置漂移
2. 你需要快速重启 Pod，且不希望修改工作负载规约
3. 你的平台对元数据变更有访问限制

该设置仅影响 Argo Rollouts 的行为，不会修改 Argo CD 的同步配置。

5. ❗ 注解行为规则与兼容性

• reloader.stakater.com/auto 和 reloader.stakater.com/search 不可同时使用——如果同时配置，auto 注解优先级更高。
• 如果同时配置了 auto 及其分类版本（secret.reloader.stakater.com/auto、configmap.reloader.stakater.com/auto），只需其中任意一个取值为 true 即可触发重载。
• 显式设置 reloader.stakater.com/auto: "false" 会直接禁用该工作负载的重载功能。
• 如果控制器开启了 --auto-reload-all 参数：
  • 所有工作负载的行为都会视同配置了 auto: "true"，除非该工作负载显式将其设置为 "false"。
  • 未配置或无法识别的注解取值会被统一视为 "false"。

6. 🔔 重载告警配置

Reloader 支持可选的告警推送功能：每当它为工作负载（例如 Deployment、StatefulSet 等）触发滚动升级时，就可以向外发送告警通知。

告警会被推送到你配置的 Webhook 端点，该端点可以是通用接收服务，也可以对接 Slack、Microsoft Teams、Google Chat 这类第三方通知服务。

如果通过 Helm 安装 Reloader，可以修改 values.yaml 中的 reloader.env.secret 字段开启该功能：

reloader:
  deployment:
    env:
      secret:
        ALERT_ON_RELOAD: "true" # 开启告警功能（默认值：false）
        ALERT_SINK: "slack" # 可选值：slack、teams、gchat 或 webhook（默认值：webhook）
        ALERT_WEBHOOK_URL: " " # 当 ALERT_ON_RELOAD 为 true 时该字段必填
        ALERT_ADDITIONAL_INFO: "Triggered by Reloader in staging environment"

7. ⏸️ Deployment 暂停重载

该功能允许你为 Deployment 设置指定时长的重载暂停周期：当多个 ConfigMap 或 Secret 在短时间内连续更新时，可以避免不必要的重复重启。

工作原理

1. 为你的 Deployment 添加 deployment.reloader.stakater.com/pause-period 注解，指定暂停时长，例如填写 "5m" 代表暂停 5 分钟。
2. 当被监控的 ConfigMap 或 Secret 发生变更时，Reloader 仍会生成重载事件，但只要 Deployment 处于暂停状态，发布操作就不会实际生效，直到暂停周期结束。
3. 该机制可以避免多个资源连续更新时触发重复重启。

适用场景

1. ✅ 你的 Deployment 引用了多个可能同时更新的 ConfigMap 或 Secret。
2. ✅ 你希望尽可能减少无意义的发布操作，降低连续配置变更导致的服务中断风险。

8. 🔐 CSI Secret Provider 支持

Reloader 兼容 https://secrets-store-csi-driver.sigs.k8s.io/，该驱动支持将外部密钥管理服务（例如 AWS Secrets Manager、Azure Key Vault、HashiCorp Vault）中的密钥直接挂载到 Pod 内。

与原生 Kubernetes Secret 对象不同，CSI 挂载的密钥变更不会总能触发 Kubernetes 原生更新事件。Reloader 会通过监控 CSI 状态资源解决这个问题：当挂载的密钥版本发生变化时，自动重启受影响的工作负载。

工作原理

开启密钥轮换功能后，Secrets Store CSI Driver 会更新一个名为 SecretProviderClassPodStatus 的 Kubernetes 资源。该资源会记录当前 Pod 所有已挂载密钥的版本信息，Reloader 会监控该资源的变更，一旦检测到版本变化就会触发工作负载发布。

前置条件

• 集群中已安装 Secrets Store CSI Driver
• 已在 CSI 驱动中开启密钥轮换功能
• 在 Reloader 中开启 CSI 集成：启动参数设置 --enable-csi-integration=true

CSI 挂载密钥专属注解

Reloader 会通过监控 SecretProviderClassPodStatus 实现单密钥粒度的变更检测。请确保你需要监控的每个密钥都已在 SecretProviderClass 中通过 secretKey 字段完成正确定义。

apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: vault-reloader-demo
  namespace: test
spec:
  provider: vault
  parameters:
    vaultAddress: "http://vault.vault.svc:8200"
    vaultSkipTLSVerify: "true"
    roleName: "demo-role"
    objects: |
      - objectName: "password"
        secretPath: "secret/data/reloader-demo"
        secretKey: "password"

[!IMPORTANT] Reloader 会追踪单个密钥（通过 secretKey 标识）的变更。如果你的 SecretProviderClass 没有为每个对象指定 secretKey，Reloader 可能无法正确检测到更新。

注意事项与限制

• Reloader 响应 CSI 状态变更，而非直接响应外部密钥存储的更新
• 必须在 CSI 驱动中启用密钥轮转功能，才能检测到更新
• CSI 的现有限制（例如 subPath 挂载）仍然生效，这类场景可能需要手动重启 Pod
• 如果密钥已同步至 Kubernetes Secret 对象，将采用标准的 Reloader 行为，无需依赖 CSI 支持

🚀 安装

1. 📦 Helm

根据你的 Kubernetes 环境和使用偏好，可通过多种方式安装 Reloader。以下是支持的安装方法：

helm repo add stakater https://stakater.github.io/stakater-charts
helm repo update
helm install reloader stakater/reloader

➡️ 完整的 Helm 配置说明请参阅 Chart 说明文档。

2. 📄 原生清单文件

直接应用官方 Kubernetes 原生清单：

kubectl apply -f https://raw.githubusercontent.com/stakater/Reloader/master/deployments/kubernetes/reloader.yaml

3. 🧱 原生 Kustomize

使用内置的 Kustomize 支持完成部署：

kubectl apply -k https://github.com/stakater/Reloader/deployments/kubernetes

4. 🛠️ 自定义 Kustomize 配置

你可以创建自己的 kustomization.yaml，将 Reloader 的官方配置作为基础依赖：

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
- https://github.com/stakater/Reloader/deployments/kubernetes

namespace: reloader

5. ⚖️ 默认资源请求与限制

默认情况下，Reloader 部署时会配置以下资源请求和限制：

resources:
  limits:
    cpu: 150m
    memory: 512Mi
  requests:
    cpu: 10m
    memory: 128Mi

6. ⚙️ 可选运行时配置

以下参数可在 Reloader 控制器层面全局自定义其运行行为：

1. 🔁 重载行为

重载策略

当监控的 ConfigMap 或 Secret 发生变更时，Reloader 支持多种策略触发滚动更新，你可以通过 --reload-strategy 参数指定使用的策略。

• env-vars 是默认策略，可在绝大多数部署场景下正常工作。
• GitOps 环境 中推荐使用 annotations 策略，避免在 ArgoCD、Flux 等工具中引发配置漂移问题。
• 在 annotations 模式下，被删除后重新创建的 ConfigMap 或 Secret 仍会触发重载（因为 Reloader 不会追踪历史状态）。

2. 🚫 资源过滤

[!NOTE] 同一时间只能忽略一种资源类型。尝试同时忽略 configmaps 和 secrets 会导致 Reloader 运行报错。 ✅ 临时替代方案：如果你需要完全禁用 Reloader，可以将其 Deployment 副本数缩放至 0。

💡 工作负载类型配置示例：

# 仅忽略 Job 类型
--ignored-workload-types=jobs

# 仅忽略 CronJob 类型
--ignored-workload-types=cronjobs

# 同时忽略两种类型（使用逗号分隔）
--ignored-workload-types=jobs,cronjobs

🔧 使用场景：当你不希望特定类型的工作负载被自动重载时，忽略指定工作负载类型的功能非常实用。

3. 🧩 命名空间过滤

4. 📝 注解键自定义

以下参数支持你自定义工作负载或资源上使用的注解键名：

5. ⚖️ 高可用

当通过 --enable-ha 参数运行多副本实例时，Reloader 会基于 Kubernetes Lease 机制实现领导者选举。以下参数可用于调整 client-go 领导者选举的相关时序配置：

租约时长必须为不小于 1s 的整秒数值：由于租约信息在 Lease 资源中以整秒形式持久化存储，跟随节点会依据该存储值判断租约是否过期，非整数的租约时长会被截断，这可能导致跟随节点判定租约已过期的时间早于现任领导者到达续订截止时间，进而同时出现两个领导者。此外租约时长必须大于续订截止时间，而续订截止时间必须大于重试周期乘以抖动系数 1.2 所得的结果。设置更长的参数值可减少 API 服务器流量，提升对低速网络的容忍度；设置更短的参数值则可缩短领导者异常后的故障切换间隔。

6. 🕷️ 调试

兼容性

Reloader 兼容 Kubernetes 1.19 及以上版本。

🏢 采用者

Reloader 在全球数千个 Kubernetes 集群中的 Docker 拉取量已超过 240 亿次。

如果您正在生产环境中使用 Reloader，欢迎向我们反馈：

• 💬 分享您的使用案例 → https://github.com/stakater/Reloader/discussions/1137
• 🏷️ 添加您的企业 Logo → ADOPTERS.md

查看所有 Reloader 用户 →

帮助

有疑问？

请在 GitHub 提交 https://github.com/stakater/Reloader/issues。

在 Slack 上与我们交流

加入 Slack 群组即可与我们讨论 Reloader 相关问题：

贡献指南

分支与 PR 命名规则

• master 分支当前处于功能冻结状态，仅接受 Bug 修复（fix:）和维护类变更（chore:）。
• v2 为当前活跃开发分支，所有新功能请提交至 v2 分支。

拉取请求标题必须遵循 https://www.conventionalcommits.org/ 规范，例如 fix(chart): correct probe port。在 v2 分支下允许使用以下前缀：feat、fix、chore、docs、refactor、perf、test、ci、build 以及 revert。

Bug 反馈与功能需求

请通过 https://github.com/stakater/Reloader/issues 提交任意 Bug 反馈或功能需求。

开发流程

1. 部署 Reloader
2. 运行 okteto up 启动开发容器
3. 执行 make build 完成构建
4. 运行 ./Reloader 启动程序

我们欢迎所有拉取请求，项目整体遵循标准的 "fork-and-pull" Git 工作流：

1. 在 GitHub 上 Fork 本仓库
2. 将 Fork 后的项目 克隆 到本地开发环境
3. 在本地专属分支中提交您的代码变更
4. 将变更 推送 回您 Fork 后的远程仓库
5. 提交 Pull Request 供我们审核

[!NOTE] 在提交拉取请求前，请务必先合并上游仓库的最新代码！

发布流程

仓库 GitHub 发布：应社区在 https://github.com/stakater/Reloader/issues/685 中的需求，Reloader 现已采用手动发布流程。不再在每个 PR 合并到主分支后自动发布版本，而是按需手动触发发布。

执行 GitHub 发布的步骤如下：

1. 代码维护人员从 master 分支创建名为 release-vX.Y.Z 的发布分支
2. 代码维护人员运行 https://github.com/stakater/Reloader/actions/workflows/init-branch-release.yaml 工作流，在发布分支上自动生成版本号与资源清单
   • 将 TARGET_BRANCH 参数设置为目标发布分支，即 release-vX.Y.Z
   • 将 TARGET_VERSION 参数设置为不带前缀 v 的目标版本号，即 X.Y.Z
3. 系统将自动创建用于更新发布分支镜像版本的 PR，示例参考：https://github.com/stakater/Reloader/pull/798
4. 代码维护人员创建标签为 vX.Y.Z、目标分支为 release-vX.Y.Z 的 GitHub 发布，该操作将触发对应镜像的构建
5. 代码维护人员从 master 分支新建分支，同时更新 Helm Chart 版本与 Reloader 镜像版本
   • 代码维护人员创建带有 release/helm-chart 标签的 PR，示例参考：https://github.com/stakater/Reloader/pull/846

仓库 Git 标签：当代码推送到主分支时，系统会自动生成名为 merge-${{ github.event.number }} 的合并镜像与合并标签，例如当编号为 800 的拉取请求被合并后，将生成标签 merge-800。

更新日志

您可以在 https://github.com/stakater/Reloader/releases 查看每个版本的变更内容。

许可证

Apache2 © Stakater

关于 Stakater

Reloader 由 Stakater 维护。如果您觉得本项目有用，欢迎通过 *** 与我们取得联系。

您可以查看 https://github.com/stakater，如果有专业服务需求或任何疑问，也请通过 *** 联系我们。