# stakater/Reloader: automatic Kubernetes rollouts when ConfigMaps and Secrets change

> Reloader is an Apache-2.0 Kubernetes controller that watches ConfigMaps and Secrets and triggers rolling upgrades on the workloads that reference them. It is annotation-driven, so adoption is per workload rather than cluster-wide.

**stakater/Reloader** — A Kubernetes controller to watch changes in ConfigMap and Secrets and do rolling upgrades on Pods with their associated Deployment, StatefulSet, DaemonSet and DeploymentConfig – [✩Star] if you're using it!

- Repository: https://github.com/stakater/Reloader
- Website: https://docs.stakater.com/reloader/
- Stars: 10,444 · Forks: 666
- Language: Go
- License: Apache-2.0
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/stakater-reloader

## The stale-config problem Reloader addresses

Kubernetes treats a ConfigMap or Secret as an ordinary object. Editing one changes what is stored in etcd, and that is all it does. A Deployment whose containers consume the ConfigMap through envFrom keeps the environment variables it started with. The kubelet does not restart the container, the Deployment controller sees no change to the pod template, and no new ReplicaSet is created. The README states this plainly: updating a Secret or ConfigMap does not automatically restart or redeploy workloads, which can leave stale configuration running in production. For credentials and feature flags that is the failure mode, not a cosmetic annoyance.

The workaround people reach for is a manual rollout restart, or a dummy annotation whose value is a timestamp, edited on every config change. Both work. Both depend on somebody remembering. Reloader's target user is the platform or application team that wants the restart to happen because the config changed, not because a human noticed. It is aimed at clusters where config and secrets are edited by CI/CD pipelines, by cert-manager issued Certificates, or by operators such as ExternalSecret and SealedSecret, all of which the README's flow diagram shows feeding into a Secret that Reloader then watches.

## How the controller decides to roll a workload

Reloader is a controller built with client-go and controller machinery; the repository's go.mod pins k8s.io/client-go v0.35.3 alongside k8s.io/api and k8s.io/apimachinery at the same version. It watches Secrets and ConfigMaps, and optionally CSI-mounted secrets, which is why sigs.k8s.io/secrets-store-csi-driver appears in the module requirements. When a watched object changes, the controller looks for workloads that should react and triggers a rollout.

The decision is annotation-driven, and the annotations are the interesting part because they encode three different policies. reloader.stakater.com/auto set to true reloads a workload when any referenced ConfigMap or Secret changes. secret.reloader.stakater.com/auto narrows that to Secrets only, and configmap.reloader.stakater.com/auto narrows it to ConfigMaps only. A second family, secret.reloader.stakater.com/reload and configmap.reloader.stakater.com/reload, takes a named resource and reloads the workload when that named object changes regardless of whether the pod spec references it at all. That last distinction matters: the README describes it as useful in tightly scoped scenarios where configuration is shared but only some consumers should restart.

Rollouts are not limited to Deployments. The README's diagram lists Deployment, DeploymentConfig, DaemonSet, StatefulSet and ArgoRollout as rollout targets, plus CronJob for job triggering and Slack, Teams or Webhook for notifications. DeploymentConfig and the OpenShift client libraries in go.mod (github.com/openshift/api and github.com/openshift/client-go) indicate that OpenShift is a first-class target rather than an afterthought, and the argo-rollouts module requirement is what backs the ArgoRollout path.

## Installing Reloader and annotating a first workload

The README points to an installation section rather than reproducing the steps, and the repository carries a deployments/ directory plus a Helm chart whose tags appear in the release list (chart-v2.2.17, chart-v2.2.16). The chart is the practical route for most clusters. The exact chart values are not reproduced in the README, so read the chart before you set anything beyond the defaults.

The first real use is two steps. Install the controller, then annotate a workload. The README's own example is a Deployment that consumes a ConfigMap and a Secret through envFrom:

```yaml
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
```

According to the README, this annotation tells Reloader to watch the ConfigMap and Secret referenced in the deployment, and when either is updated it triggers a rollout. The observable result is a new ReplicaSet and fresh pods; you can confirm it with a normal rollout status check on the Deployment after editing my-config or my-secret.

If you would rather not opt in per workload, the annotation family supports the reverse: reload everything by default and exclude the workloads you do not want restarted. The README lists exclusion as one of the supported controls. Pick one direction early, because a cluster where some teams annotate and others rely on a default is a cluster where nobody can predict which pods will bounce when a shared ConfigMap is edited.

## Where Reloader is the wrong tool

Reloader restarts workloads. It does not make a running process re-read its configuration. If your application reads a config file once at startup, a restart is exactly what you want. If your application already watches its own config and hot-reloads, Reloader will kill working pods for no benefit, and the annotation is a liability rather than a convenience.

The mounted-volume case deserves care. A ConfigMap projected into a pod as a volume is updated in place by the kubelet, so the file on disk changes without a restart. Reloader's annotation still triggers a rollout, which is often the right call for a process that will not re-read the file, but it is a different situation from envFrom, where the old values persist until the pod is replaced. Treating both cases as one is how teams end up with unexpected restarts during a config edit window.

The README also notes that full documentation lives on a separate documentation site, and the repository README itself is truncated in places. If you need to know precisely how the controller behaves when a Secret is deleted and recreated, or how it reacts to rapid successive edits, that answer is not in the README. The repository has a test/ directory and the Makefile exposes a test target, so the behaviour is exercised somewhere, but you should confirm it against your own cluster rather than assuming.

One more boundary: Reloader is a controller that watches and reacts. It is not a secret manager. It does not generate credentials, rotate them on a schedule, or sync them from an external store. It reacts to Secrets that something else produced.

## Reloader compared with a GitOps-driven rollout

The obvious alternative is not another controller of the same shape. It is Argo CD or Flux, where the ConfigMap and Secret live in Git, and the deployment's pod template changes whenever the config changes because the pipeline rewrites the manifest. In that model the rollout is a side effect of the desired state being different, and there is no separate watcher to configure.

The difference is where the trigger lives. With GitOps, the trigger is the commit: nothing rolls until a change is merged and reconciled, which gives you an audit trail and a review step, and it means an out-of-band kubectl edit of a ConfigMap does not restart anything. With Reloader, the trigger is the object change itself, so a kubectl edit, an operator writing a Secret, or a cert-manager renewal all cause rollouts without a commit. That is the point of the tool, and it is also the risk: an out-of-band edit becomes a production event.

There is a middle path worth naming. If your config is already in Git but a controller such as ExternalSecret or SealedSecret materialises the Secret at runtime, the GitOps manifest for the Secret may not change even though the resulting Secret does. In that case GitOps alone will not restart the workload, and Reloader covers a real gap. The README's flow diagram shows exactly this: ExternalSecret, SealedSecret and Certificate create a Secret, and Reloader watches the Secret. Reloader and GitOps are not mutually exclusive; they cover different links in the chain.

## Licence, maintenance and the upgrade path

Reloader is Apache-2.0. That is a permissive licence, and it means you can use, modify and redistribute it, including in a commercial product, provided you keep the licence and notices intact. It is not legal advice; read LICENSE in the repository if the distinction matters to your organisation. The README also describes a separate Reloader Enterprise offering with signed images, SBOMs, SLA-backed support and a dedicated escalation path. The open source controller and the enterprise offering are distinct; nothing in the README suggests the Apache-2.0 controller is feature-limited by the enterprise tier, but the two are marketed together.

On maintenance, the repository is not archived, and the last push was on 2026-09-21. Releases are frequent: v1.4.22 and chart-v2.2.17 both landed on 2026-09-09, with chart-v2.2.16 on 2026-08-10. The controller and the Helm chart are versioned separately, which is the upgrade cost to plan for. A chart bump and a controller image bump are two different changes, and the chart tag does not tell you which controller version it deploys. Pin both explicitly in your values rather than tracking latest.

The build is a static Go binary on a distroless nonroot base, per the Dockerfile, exposing port 9090 for metrics and probes and running as UID 65532. There is a second Dockerfile.ubi and UBI build file lists in the repository root, which suggests a Red Hat oriented image variant exists. If you are on OpenShift, that variant is worth checking before you default to the distroless image.

## Conclusion

Adopt Reloader if you run Kubernetes workloads whose configuration lives in ConfigMaps or Secrets and you are tired of editing a deployment to force a restart. Skip it if your configuration is baked into images at build time, or if you already have a GitOps pipeline that writes a new pod template hash on every config change; in that case Reloader adds a second, invisible cause of rollouts. Before you annotate anything, verify which of your workloads use envFrom versus a mounted volume, because a mounted ConfigMap updates in place and Reloader's value there is different. Then check whether argoproj/argo-rollouts is present in the cluster, since Reloader ships an ArgoRollout path and that dependency is compiled in, not optional at install time.

## FAQ

### What is Reloader in Kubernetes?

It is a Kubernetes controller that watches changes in ConfigMaps and Secrets and triggers rolling upgrades on the workloads that reference them, such as Deployments, StatefulSets, DaemonSets and DeploymentConfigs. Kubernetes itself does not restart pods when a referenced ConfigMap or Secret is updated, and Reloader fills that gap.

### How do you use Reloader on a Deployment?

Add the annotation reloader.stakater.com/auto with the value true to the workload's metadata. The README's example shows a Deployment that consumes a ConfigMap and a Secret through envFrom, and states that when either is updated Reloader triggers a rollout.

### Can Reloader watch only Secrets or only ConfigMaps?

Yes. secret.reloader.stakater.com/auto reloads a workload only when referenced Secrets change, and configmap.reloader.stakater.com/auto does the same for ConfigMaps. The plain reloader.stakater.com/auto annotation reacts to either kind.

### Which workload types can Reloader roll?

The README lists Deployment, DeploymentConfig, DaemonSet, StatefulSet and ArgoRollout as rollout targets, plus CronJob for job triggering. It also lists Slack, Teams and Webhook as notification destinations.

### What licence is stakater/Reloader released under?

Apache-2.0. The repository also describes a separate Reloader Enterprise offering with signed images, SBOMs and SLA-backed support, which is distinct from the open source controller.

## Sources

- [License: Apache-2.0](https://github.com/stakater/Reloader/blob/master/LICENSE)
- [Project website](https://docs.stakater.com/reloader/)
- [README](https://github.com/stakater/Reloader/blob/master/README.md)
- [Releases](https://github.com/stakater/Reloader/releases)
- [stakater/Reloader on GitHub](https://github.com/stakater/Reloader)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/stakater-reloader