Reloader — Auto-Restart Kubernetes Pods on Config Changes

Introduction

Kubernetes does not restart pods when a mounted ConfigMap or Secret changes. Reloader fills that gap by watching for updates and triggering rolling restarts on the associated workloads, ensuring your applications always pick up the latest configuration.

What Reloader Does

• Watches Kubernetes ConfigMaps and Secrets for data changes
• Triggers rolling updates on Deployments, StatefulSets, and DaemonSets
• Supports annotation-based opt-in per workload or per resource name
• Works with both mounted volumes and environment variable references
• Runs as a single controller pod with minimal resource usage

Architecture Overview

Reloader is a Go controller that uses the Kubernetes informer framework to subscribe to ConfigMap and Secret change events. When it detects a data modification, it looks up workloads that reference the changed resource via annotations. It then patches the pod template with an updated hash annotation, which causes the Kubernetes rollout controller to perform a rolling restart.

Self-Hosting & Configuration

• Install via Helm chart, Kustomize manifests, or plain YAML from the releases page
• Add the annotation reloader.stakater.com/auto: "true" to workloads for automatic tracking
• Use reloader.stakater.com/search: "true" on specific ConfigMaps or Secrets for fine-grained control
• Set RELOAD_STRATEGY environment variable to env-vars or annotations based on your needs
• Limit watched namespaces with --namespaces-to-ignore or --resources-to-ignore flags

Key Features

• Zero-code integration via Kubernetes annotations
• Supports Deployments, DaemonSets, StatefulSets, and Rollouts
• Configurable reload strategies including env-var hash injection
• Namespace filtering to scope the watch to specific parts of the cluster
• Lightweight single-pod deployment with low CPU and memory footprint

Comparison with Similar Tools

• Wave (Spot) — Similar ConfigMap watcher but less actively maintained; Reloader has broader community adoption
• Manual kubectl rollout restart — Requires human intervention or scripting; Reloader automates it
• Kustomize configMapGenerator — Generates unique names per change but requires redeployment; Reloader works with in-place updates
• ArgoCD auto-sync — Re-applies manifests but does not detect ConfigMap data changes within the same manifest hash

FAQ

Q: Does Reloader restart all pods in the cluster? A: No. It only restarts workloads that carry the Reloader annotation and reference the changed ConfigMap or Secret.

Q: Can I use it with Argo Rollouts? A: Yes. Reloader supports Argo Rollouts as a workload kind in addition to standard Kubernetes resources.

Q: What happens if the ConfigMap change is rolled back? A: Reloader detects the rollback as another change and triggers a fresh rolling restart with the reverted configuration.

Q: Does it work in a multi-tenant cluster? A: Yes. Use namespace filtering to restrict Reloader to specific namespaces and avoid cross-tenant restarts.

Sources

• https://github.com/stakater/Reloader
• https://docs.stakater.com/reloader