How to Enable Hot Reload of ConfigMaps and Secrets in Kubernetes with Reloader

Background

Configuration center problems:

Immutable configuration can be baked into images, but how to handle mutable configuration?

Leaking sensitive data (passwords, keys) poses security risks.

Every config change forces a new image build and deployment, increasing storage and management overhead.

Highly customized solutions lack scalability and reusability.

Usage:

ConfigMap or Secret can be injected into a pod either as environment variables or as a mounted volume. Environment‑variable injection does not support hot updates, while volume mounting does, provided the application monitors the file changes.

Env‑based injection requires a rolling pod restart to take effect.

Volume‑based injection needs the application to watch ConfigMap changes or periodically reload the configuration.

If the application cannot reload, a sidecar container can monitor ConfigMap updates and trigger a pod restart.

Solution

ConfigMap and Secret are standard Kubernetes objects for storing configuration data. When mounted as a volume, kubelet periodically updates the files, but environment‑variable injection cannot detect updates.

To make a pod aware of ConfigMap or Secret changes, you can use workarounds such as:

In‑otify‑based file watching combined with a readiness probe.

Rolling upgrades triggered by an external tool.

Reloader Overview

What is Reloader?

Reloader watches ConfigMap and Secret objects and automatically performs rolling upgrades on Deployments, DaemonSets, StatefulSets, and other workloads when changes are detected.

Installation

Helm:

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

Kustomize:

kubectl apply -k https://github.com/stakater/Reloader/deployments/kubernetes

Manifest:

kubectl apply -f https://raw.githubusercontent.com/stakater/Reloader/master/deployments/kubernetes/reloader.yaml

Configuration Ignoring

Reloader can ignore specific ConfigMaps or Secrets via arguments in the reloader deployment spec, e.g.,

--resources-to-ignore=configMaps

or

--resources-to-ignore=secrets

.

Annotations

reloader.stakater.com/auto: "true"

– automatically restart pods when any referenced ConfigMap or Secret changes.

reloader.stakater.com/search: "true"

– enables selective watching; only objects annotated with

reloader.stakater.com/match: "true"

will trigger a restart.

Example Deployment annotation to reload a specific ConfigMap:

metadata:
  annotations:
    configmap.reloader.stakater.com/reload: "nginx-cm1"

Example Secret annotation:

metadata:
  annotations:
    secret.reloader.stakater.com/reload: "foo-secret"

Testing

Deploy a sample Nginx pod that mounts

nginx-cm

as a volume, then edit the ConfigMap. Reloader detects the change and triggers a rolling update, resulting in a new pod that loads the updated configuration.

# Deploy
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 1
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx
        volumeMounts:
        - name: nginx-cm
          mountPath: /data/cfg
          readOnly: true
      volumes:
      - name: nginx-cm
        configMap:
          name: nginx-cm
          items:
          - key: config.yaml
            path: config.yaml
            mode: 0644

# ConfigMap
apiVersion: v1
kind: ConfigMap
metadata:
  name: nginx-cm
  annotations:
    reloader.stakater.com/match: "true"
data:
  config.yaml: |
    # project settings
    DEFAULT_CONF:
      port: 8888

# Verify rolling update
kubectl get po
kubectl edit cm nginx-cm
# Observe new pod created

Notes

Reloader is a cluster‑wide resource; deploy it in a common namespace for reuse.

reloader.stakater.com/auto

works on Deployments, DaemonSets, StatefulSets, etc.

Annotations

secret.reloader.stakater.com/reload

or

configmap.reloader.stakater.com/reload

cause a pod restart when the referenced object changes.

reloader.stakater.com/search

and

reloader.stakater.com/auto

cannot be used together on the same workload.

Reflection

Reloader watches ConfigMaps and Secrets and automatically triggers rolling upgrades of workloads, providing a convenient way to achieve hot configuration reload without modifying the application code.

Reference

https://github.com/stakater/Reloader