Reloader: how one annotation turns a ConfigMap edit into a rollout

reloader.stakater.com/auto turns reference discovery into a restart

Kubernetes does not restart a pod when a Secret or ConfigMap it reads is updated, so a rollout has to be triggered by something outside the workload. Reloader is that something: a controller that watches Secrets and ConfigMaps and then rolls out the workloads that reference them. The smallest useful configuration is a single annotation on a 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

The discovery is automatic. Reloader reads the references in the pod spec, in this case the two entries under envFrom, and treats a change to either object as a reason to roll the Deployment. The cost of that convenience is precision: with auto mode, any ConfigMap or Secret attached to the pod is a restart trigger.

secret.auto and configmap.auto split the trigger without narrowing the scope

Three annotation keys cover the common cases, and the difference between them is which object type counts as a change. `reloader.stakater.com/auto: "true"` reacts to any referenced ConfigMap or Secret. `secret.reloader.stakater.com/auto: "true"` reacts only to referenced Secrets, and `configmap.reloader.stakater.com/auto: "true"` reacts only to referenced ConfigMaps. The narrower keys still rely on automatic reference discovery, so switching to the secret variant does not narrow which Secrets are considered, only which kinds of change count. For a Deployment that mounts a frequently rotated token and a rarely touched feature flag ConfigMap, that difference is the whole point. The trade-off is bookkeeping: three separate keys with overlapping meanings, all prefixed with reloader.stakater.com.

Named reload annotations fire on objects the pod spec never mentions

The escape hatch from discovery is the named form. `secret.reloader.stakater.com/reload: "my-secret"` triggers a rollout when that named Secret changes, and `configmap.reloader.stakater.com/reload: "my-config"` does the same for a named ConfigMap. The project is explicit that these fire regardless of how the resource is used, in other words regardless of whether it appears anywhere in the pod spec. Its own use cases are tightly scoped situations where config is shared but reloads matter in only certain cases, and cases where you know exactly which resources count and want to avoid auto-discovery altogether. Two consequences follow. You maintain the list by hand, so a new ConfigMap is inert until someone adds it. And the opposite failure is possible too: a named resource that no container actually reads will still cost you a rollout each time it changes.

search plus match is the opt-in pattern the readme never finishes explaining

The usage overview lists five ways to shape reload behaviour: reload all resources by default, restrict reloads to only Secrets or only ConfigMaps, watch only specific resources, opt in via tagging using search plus match, and exclude workloads you do not want to reload. That fifth option inverts the default, which matters for clusters where most workloads should stay put. The README introduces it as a targeted reload pattern in which workloads only restart if the Secret or ConfigMap is referenced by the workload and meets a further condition. The full documentation is on the Stakater documentation site.

master is feature frozen while the newest operator build is v2.0.0-beta.1

Reloader v2 was rebuilt on the Operator SDK and has been released, and all new development happens on the v2 branch. The master branch, which is Reloader v1, is feature frozen and receives only security and critical bug fixes, and new feature requests and pull requests are asked for against v2. The release list shows why that split matters right now: chart-v3.0.0-beta.5 was published on 29 October 2026, v2.0.0-beta.2 on 27 October 2026, and chart-v2.2.19 on 27 October 2026. The default branch is master, its last push is dated 29 October 2026, and the repository is not archived. So the maintenance signal is current, but a reader has three different version lines to reason about, one of them a beta.

The image is distroless, runs as 65532, and exposes only port 9090

The Dockerfile is a two stage build. The builder stage starts from golang:1.26, copies go.mod and go.sum, runs go mod download, then copies main.go, internal/, and pkg/ and compiles with CGO_ENABLED=0, GOOS and GOARCH from build arguments, and linker flags that inject VERSION, COMMIT, BUILD_DATE, and EDITION into the github.com/stakater/Reloader/pkg/common package, with EDITION defaulting to oss. The runtime stage is gcr.io/distroless/static:nonroot with WORKDIR /, the manager binary copied to the root, USER 65532:65532, EXPOSE 9090 described as the port for metrics and probes, and ENTRYPOINT ["/manager"]. Two things follow for an operator. There is no shell in the container, so debugging means rebuilding with logs rather than execing in. And EDITION is a build argument defaulting to oss, so the edition label is set at build time.

OpenShift, Argo Rollouts and the CSI driver are all linked into one binary

The dependency list in go.mod is the clearest statement of scope in the whole repository. It pins k8s.io/api, k8s.io/apimachinery, k8s.io/client-go and k8s.io/kubectl all at v0.35.3, requires github.com/argoproj/argo-rollouts v1.9.0, pulls openshift/api and openshift/client-go, and depends on sigs.k8s.io/secrets-store-csi-driver v1.5.5, which is the library side of the optional CSI mounted secrets the project advertises. github.com/spf13/cobra v1.10.2 provides the command line, github.com/prometheus/client_golang v1.23.2 the metrics served on 9090, github.com/sirupsen/logrus v1.9.4 the logging, and github.com/parnurzeal/gorequest an HTTP client library. Test dependencies are ginkgo, gomega, and testify.

The pinned build tooling sits behind the Kubernetes libraries it compiles against

The Makefile names its own versions: KUSTOMIZE_VERSION v5.3.0, CONTROLLER_TOOLS_VERSION v0.14.0, ENVTEST_VERSION release-0.17, and YQ_VERSION v4.27.5, with kustomize, controller-gen, setup-envtest, and yq fetched into a local bin directory. Images are built as ghcr.io/stakater/reloader, with IMG defaulting to that name plus the v prefixed VERSION variable, and ARCH covering arm64, arm, and amd64. Targets include build, test, push, apply, deploy, release, release-all, and manifest. The gap worth noticing is between ENVTEST_VERSION release-0.17 and the k8s.io libraries at v0.35.3: envtest downloads a control plane to test against, so a passing local run exercises a cluster API generation behind the one the code imports. The rest of the repository root is documentation and automation scaffolding, including Dockerfile.ubi with amd64 and arm64 build file lists, a golangci lint config, vale and markdownlint configs for prose, renovate, sonar, okteto, a MAINTAINERS file, and an adopters directory.

Editorial conclusion

Reloader fits clusters where config changes come from GitOps, ExternalSecret, or cert-manager and nobody wants to remember which Deployment consumes which ConfigMap. Before adopting it, decide deliberately between the feature frozen master branch and the v2 operator line, whose newest tag is v2.0.0-beta.2, and read the annotation tables closely, and check the documentation site for the opt-in search and match pattern. If you need to inspect what the controller loaded at runtime, remember the shipped image is distroless with no shell.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. stakater/Reloader on GitHub