ghcr.io/stakater/reloader:merge-1158-ubi

🔁 什么是 Reloader？

Reloader 是一个 Kubernetes 控制器，当引用的 Secrets、ConfigMaps 或可选的 CSI 挂载密钥更新时，会自动触发工作负载（如 Deployments、StatefulSets 等）的滚动更新。

在传统的 Kubernetes 环境中，更新 Secret 或 ConfigMap 不会自动重启或重新部署工作负载。这可能导致生产环境中运行的配置过时，尤其是在处理凭据、功能标志或环境配置等动态值时。

Reloader 通过确保工作负载自动、安全地与配置变更保持同步，填补了这一空白。

📚 完整文档可在 Stakater 文档网站 获取

4. ⚙️ 工作负载特定的滚动策略（仅适用于 Argo Rollouts）

[!NOTE] 此功能仅在使用 https://argoproj.github.io/argo-rollouts/ 时适用。对于标准 Kubernetes Deployments、StatefulSets 或 DaemonSets，此功能会被忽略。要使用此功能，必须在 Reloader 中启用 Argo Rollouts 支持（例如通过 --is-argo-rollouts=true）。

默认情况下，Reloader 通过更新 Pod 模板触发 Argo Rollout 控制器执行标准滚动更新。这在大多数情况下运行良好，但由于此操作会修改工作负载规范，ArgoCD 等 GitOps 工具会将其检测为“配置漂移”（Configuration Drift）并将应用标记为“不同步”（OutOfSync）。

要避免这种情况，您可以切换到 restart 策略，该策略仅重启 Pod 而不更改 Pod 模板。

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

✅ 建议在以下情况使用 restart：

1. 您正在使用 GitOps 并希望避免配置漂移
2. 您希望快速重启而不更改工作负载规范
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 等服务。

要启用此功能，请在 values.yaml 中更新 reloader.env.secret 部分（通过 Helm 安装时）：

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: "由 staging 环境中的 Reloader 触发"

7. ⏸️ 暂停部署

此功能允许您将部署的滚动更新暂停指定时长，有助于在多个 ConfigMap 或 Secret 快速连续更新时防止多次重启。

工作原理

1. 为您的 Deployment 添加 deployment.reloader.stakater.com/pause-period 注解，并指定暂停时长（例如 "5m" 表示五分钟）。
2. 当被监控的 ConfigMap 或 Secret 发生变化时，Reloader 仍会触发重载事件，但如果部署处于暂停状态，滚动更新将在暂停时长结束后才生效。
3. 这可以避免在多个资源紧密连续更新时发生重复重启。

适用场景

1. ✅ 您的部署引用了多个可能同时更新的 ConfigMap 或 Secret。
2. ✅ 您希望减少不必要的滚动更新，并降低因连续配置更改导致的 downtime。

8. 🔐 CSI 密钥提供程序支持

Reloader 支持 https://secrets-store-csi-driver.sigs.k8s.io/%EF%BC%8C%E8%AF%A5%E9%A9%B1%E5%8A%A8%E5%85%81%E8%AE%B8%E5%B0%86%E5%A4%96%E9%83%A8%E5%AF%86%E9%92%A5%E5%AD%98%E5%82%A8%EF%BC%88%E5%A6%82 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 可能无法正确检测更新。

注意事项与限制

CSI 限制（例如 subPath 挂载）仍然适用，可能需要重启 Pod。

如果密钥同步到 Kubernetes Secret 对象，则适用标准 Reloader 行为，可能不需要 CSI 支持。

发布流程

仓库 GitHub 发布：根据社区在 https://github.com/stakater/Reloader/issues/685 中提出的要求，Reloader 现已采用手动发布流程。发布不再在每次合并 PR 到 main 分支时自动进行，而是根据需求手动触发。

创建 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 标签：推送到 main 分支将创建名为 merge-${{ github.event.number }} 的合并镜像和合并标签，例如当编号为 800 的 pull request 合并时，将创建 merge-800。

变更日志

查看 https://github.com/stakater/Reloader/releases 了解每个版本的变更内容。

许可证

Apache2 © Stakater

关于 Stakater

Reloader 由 Stakater 维护。如果您喜欢它，请通过 *** 告诉我们。

查看 https://github.com/stakater%EF%BC%8C%E6%88%96%E5%A6%82%E9%9C%80%E4%B8%93%E4%B8%9A%E6%9C%8D%E5%8A%A1%E5%92%8C%E5%92%A8%E8%AF%A2%EF%BC%8C%E8%AF%B7%E9%80%9A%E8%BF%87 *** 联系我们。