Reloader

Automatically restart pods when their ConfigMaps or Secrets change.

Time: ~10 minutes Difficulty: Beginner

What You Will Learn

How Stakater Reloader watches ConfigMaps and Secrets
Three reload modes: auto, specific, and no-reload
Why pods do not pick up config changes without a restart
How to trigger rolling restarts automatically on config updates
When to use each annotation mode

Prerequisites

Install Stakater Reloader using Helm:

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

Wait for Reloader to be ready:

kubectl wait --for=condition=ready pod -l app.kubernetes.io/name=reloader -n reloader --timeout=60s

Deploy

Navigate to the demo directory:

cd demos/reloader

Deploy the resources:

kubectl apply -f manifests/namespace.yaml
kubectl apply -f manifests/configmap.yaml
kubectl apply -f manifests/secret.yaml
kubectl apply -f manifests/deployment-auto.yaml
kubectl apply -f manifests/deployment-specific.yaml
kubectl apply -f manifests/deployment-ignored.yaml
kubectl apply -f manifests/service.yaml

Wait for all pods to be ready:

kubectl wait --for=condition=ready pod -l app -n reloader-demo --timeout=60s

Verify

Check that all three deployments are running:

kubectl get deployments -n reloader-demo
kubectl get pods -n reloader-demo

You should see three deployments, each with 2 replicas:

web-auto (watches all referenced ConfigMaps and Secrets)
web-specific (watches only the app-config ConfigMap)
web-ignored (no Reloader annotation, will not auto-restart)

Update the ConfigMap and watch the magic happen

Open a watch window to see pod restarts in real time:

kubectl get pods -n reloader-demo -w

In another terminal, update the ConfigMap:

kubectl patch configmap app-config -n reloader-demo \
  --type=merge -p '{"data":{"APP_MESSAGE":"Hello from v2"}}'

You will see:

web-auto pods: rolling restart triggered (new pods created, old ones terminated)
web-specific pods: rolling restart triggered (watches app-config)
web-ignored pods: NO restart (still running with old config)

Verify the restart happened

Check pod ages after the update:

kubectl get pods -n reloader-demo -o wide

The web-auto and web-specific pods will have a recent creation time, while web-ignored pods remain old.

Verify the new config is loaded:

kubectl exec deploy/web-auto -n reloader-demo -- env | grep APP_MESSAGE
kubectl exec deploy/web-specific -n reloader-demo -- env | grep APP_MESSAGE
kubectl exec deploy/web-ignored -n reloader-demo -- env | grep APP_MESSAGE

The first two will show “Hello from v2”, while web-ignored still shows “Hello from v1”.

What is Happening

manifests/
  namespace.yaml              # reloader-demo namespace
  configmap.yaml              # ConfigMap with APP_MESSAGE and index.html
  secret.yaml                 # Secret with DB_PASSWORD and API_KEY
  deployment-auto.yaml        # Watches ALL referenced ConfigMaps and Secrets
  deployment-specific.yaml    # Watches only the app-config ConfigMap
  deployment-ignored.yaml     # No Reloader annotation (control group)
  service.yaml                # ClusterIP services for each deployment

Stakater Reloader solves the classic Kubernetes problem: updating a ConfigMap or Secret does not restart pods automatically. Pods that inject config as environment variables never see updates. Pods that mount config as volumes can see updates after a kubelet sync delay (10-60 seconds), but only if the volume is mounted as a directory, not a subPath.

Reloader monitors ConfigMaps and Secrets. When a change is detected, it triggers a rolling restart of the Deployment, StatefulSet, or DaemonSet. The restart is done by updating a pod template annotation, which Kubernetes treats as a spec change.

Three annotation modes:

Annotation	Watches	Use Case
`reloader.stakater.com/auto: "true"`	All referenced ConfigMaps and Secrets	Simple setup, watches everything
`configmap.reloader.stakater.com/reload: "name"`	Specific ConfigMap(s)	Fine-grained control, only restart for certain configs
`secret.reloader.stakater.com/reload: "name"`	Specific Secret(s)	Fine-grained control for Secrets
(no annotation)	Nothing	Pods keep running with old config until manual restart

You can specify multiple resources in the specific mode by separating them with commas: configmap.reloader.stakater.com/reload: "config1,config2".

Experiment

Update the Secret and observe that only web-auto restarts (since web-specific only watches ConfigMaps):

kubectl patch secret app-secret -n reloader-demo \
  --type=merge -p '{"stringData":{"DB_PASSWORD":"super-secret-v2"}}'

kubectl get pods -n reloader-demo -w

Add a Secret-specific annotation to web-specific and update the Secret again:

kubectl patch deployment web-specific -n reloader-demo \
  --type=merge -p '{"metadata":{"annotations":{"secret.reloader.stakater.com/reload":"app-secret"}}}'

kubectl patch secret app-secret -n reloader-demo \
  --type=merge -p '{"stringData":{"DB_PASSWORD":"super-secret-v3"}}'

Add the auto annotation to web-ignored and verify it now restarts on config changes:

kubectl patch deployment web-ignored -n reloader-demo \
  --type=merge -p '{"metadata":{"annotations":{"reloader.stakater.com/auto":"true"}}}'

kubectl patch configmap app-config -n reloader-demo \
  --type=merge -p '{"data":{"APP_MESSAGE":"Hello from v3"}}'

Check Reloader logs to see it detecting and processing config changes:
Terminal window
```
kubectl logs -f deployment/reloader-reloader -n reloader
```
Try the search and match mode (advanced): add reloader.stakater.com/search: "true" to a Deployment and reloader.stakater.com/match: "true" to a ConfigMap. Reloader will watch all ConfigMaps with the match annotation.

Cleanup

Delete the demo namespace:

kubectl delete namespace reloader-demo

Optionally, uninstall Reloader:

helm uninstall reloader -n reloader
kubectl delete namespace reloader

Next Step

Move on to Knative Serving to learn about serverless workloads on Kubernetes with scale-to-zero and revision-based traffic splitting.