🔁 What is Reloader?
Reloader is a Kubernetes controller that automatically triggers rollouts of workloads (like Deployments, StatefulSets, and more) whenever referenced Secrets, ConfigMaps or optionally CSI-mounted secrets are updated.
In a traditional Kubernetes setup, updating a Secret or ConfigMap does not automatically restart or redeploy your workloads. This can lead to stale configurations running in production, especially when dealing with dynamic values like credentials, feature flags, or environment configs.
Reloader bridges that gap by ensuring your workloads stay in sync with configuration changes — automatically and safely.
📚 Full documentation is available at Stakater documentation site
🚀 Why Reloader?
- ✅ Zero manual restarts: No need to manually rollout workloads after config/secret changes.
- 🔒 Secure by design: Ensure your apps always use the most up-to-date credentials or tokens.
- 🛠️ Flexible: Works with all major workload types — Deployment, StatefulSet, Daemonset, ArgoRollout, and more.
- ⚡ Fast feedback loop: Ideal for CI/CD pipelines where secrets/configs change frequently.
- 🔄 Out-of-the-box integration: Just label your workloads and let Reloader do the rest.
🔧 How It Works?
flowchart LR
ExternalSecret -->|Creates| Secret
SealedSecret -->|Creates| Secret
Certificate -->|Creates| Secret
Secret -->|Watched by| Reloader
ConfigMap -->|Watched by| Reloader
Reloader -->|Triggers Rollout| Deployment
Reloader -->|Triggers Rollout| DeploymentConfig
Reloader -->|Triggers Rollout| Daemonset
Reloader -->|Triggers Rollout| Statefulset
Reloader -->|Triggers Rollout| ArgoRollout
Reloader -->|Triggers Job| CronJob
Reloader -->|Sends Notification| Slack,Teams,Webhook
- Sources like
ExternalSecret, SealedSecret, or Certificate from cert-manager can create or manage Kubernetes Secrets — but they can also be created manually or delivered through GitOps workflows.
Secrets and ConfigMaps are watched by Reloader.- When changes are detected, Reloader automatically triggers a rollout of the associated workloads, ensuring your app always runs with the latest configuration.
🏢 Reloader Enterprise
Reloader OSS is free and production-proven with 24B+ downloads.
For teams with stricter requirements:
| Need |
Enterprise |
| CVE-free, signed images with SBOM |
✅ |
| SLA-backed support from Kubernetes experts |
✅ |
| Artifact provenance for compliance audits |
✅ |
| Dedicated escalation path |
✅ |
→ Contact Sales for info about Reloader Enterprise.
⚡ Quick Start
1. Install Reloader
Follow any of this installation options.
2. Annotate Your Workload
To enable automatic reload for 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
This tells Reloader to watch the ConfigMap and Secret referenced in this deployment. When either is updated, it will trigger a rollout.
🧩 Usage
Reloader supports multiple annotation-based controls to let you customize when and how your Kubernetes workloads are reloaded upon changes in Secrets or ConfigMaps.
Kubernetes does not trigger pod restarts when a referenced Secret or ConfigMap is updated. Reloader bridges this gap by watching for changes and automatically performing rollouts — but it gives you full control via annotations, so you can:
- Reload all resources by default
- Restrict reloads to only Secrets or only ConfigMaps
- Watch only specific resources
- Use opt-in via tagging (
search + match)
- Exclude workloads you don’t want to reload
1. 🔁 Automatic Reload (Default)
Use these annotations to automatically restart the workload when referenced Secrets or ConfigMaps change.
| Annotation |
Description |
reloader.stakater.com/auto: "true" |
Reloads workload when any referenced ConfigMap or Secret changes |
secret.reloader.stakater.com/auto: "true" |
Reloads only when referenced Secret(s) change |
configmap.reloader.stakater.com/auto: "true" |
Reloads only when referenced ConfigMap(s) change |
2. 📛 Named Resource Reload (Specific Resource Annotations)
These annotations allow you to manually define which ConfigMaps or Secrets should trigger a reload, regardless of whether they're used in the pod spec.
| Annotation |
Description |
secret.reloader.stakater.com/reload: "my-secret" |
Reloads when specific Secret(s) change, regardless of how they're used |
configmap.reloader.stakater.com/reload: "my-config" |
Reloads when specific ConfigMap(s) change, regardless of how they're used |
Use when
- ✅ This is useful in tightly scoped scenarios where config is shared but reloads are only relevant in certain cases.
- ✅ Use this when you know exactly which resource(s) matter and want to avoid auto-discovery or searching altogether.
3. 🎯 Targeted Reload (Match + Search Annotations)
This pattern allows fine-grained reload control — workloads only restart if the Secret/ConfigMap is both:
- Referenced by the workload
- Explicitly annotated with
match: true
| Annotation |
Applies To |
Description |
reloader.stakater.com/search: "true" |
Workload |
Enables search mode (only reloads if matching secrets/configMaps are found) |
reloader.stakater.com/match: "true" |
ConfigMap/Secret |
Marks the config/secret as eligible for reload in search mode |
How it works
- The workload must have:
reloader.stakater.com/search: "true"
- The ConfigMap or Secret must have:
reloader.stakater.com/match: "true"
- The resource (ConfigMap or Secret) must also be referenced in the workload (via env,
volumeMount, etc.)
Use when
- ✅ You want to reload a workload only if it references a ConfigMap or Secret that has been explicitly tagged with
reloader.stakater.com/match: "true".
- ✅ Use this when you want full control over which shared or system-wide resources trigger reloads. Great in multi-tenant clusters or shared configs.
⛔ Resource-Level Ignore Annotation
When you need to prevent specific ConfigMaps or Secrets from triggering any reloads, use the ignore annotation on the resource itself:
apiVersion: v1
kind: ConfigMap # or Secret
metadata:
name: my-config
annotations:
reloader.stakater.com/ignore: "true"
This instructs Reloader to skip all reload logic for that resource across all workloads.
4. ⚙️ Workload-Specific Rollout Strategy (Argo Rollouts Only)
Note: This is only applicable when using Argo Rollouts. It is ignored for standard Kubernetes Deployments, StatefulSets, or DaemonSets. To use this feature, Argo Rollouts support must be enabled in Reloader (for example via --is-argo-rollouts=true).
By default, Reloader triggers the Argo Rollout controller to perform a standard rollout by updating the pod template. This works well in most cases, however, because this modifies the workload spec, GitOps tools like ArgoCD will detect this as "Configuration Drift" and mark your application as OutOfSync.
To avoid that, you can switch to the restart strategy, which simply restarts the pod without changing the pod template.
metadata:
annotations:
reloader.stakater.com/rollout-strategy: "restart"
| Value |
Behavior |
rollout (default) |
Updates pod template metadata to trigger a rollout |
restart |
Deletes the pod to restart it without patching the template |
✅ Use restart if:
- You're using GitOps and want to avoid drift
- You want a quick restart without changing the workload spec
- Your platform restricts metadata changes
This setting affects Argo Rollouts behavior, not Argo CD sync settings.
5. ❗ Annotation Behavior Rules & Compatibility
reloader.stakater.com/auto and reloader.stakater.com/search cannot be used together — the auto annotation takes precedence.- If both
auto and its typed versions (secret.reloader.stakater.com/auto, configmap.reloader.stakater.com/auto) are used, only one needs to be true to trigger a reload.
- Setting
reloader.stakater.com/auto: "false" explicitly disables reload for that workload.
- If
--auto-reload-all is enabled on the controller:
- All workloads are treated as if they have
auto: "true" unless they explicitly set it to "false".
- Missing or unrecognized annotation values are treated as
"false".
6. 🔔 Alerting on Reload
Reloader can optionally send alerts whenever it triggers a rolling upgrade for a workload (e.g., Deployment, StatefulSet, etc.).
These alerts are sent to a configured webhook endpoint, which can be a generic receiver or services like Slack, Microsoft Teams or Google Chat.
To enable this feature, update the reloader.env.secret section in your values.yaml (when installing via Helm):
reloader:
deployment:
env:
secret:
ALERT_ON_RELOAD: "true" # Enable alerting (default: false)
ALERT_SINK: "slack" # Options: slack, teams, gchat or webhook (default: webhook)
ALERT_WEBHOOK_URL: "<your-webhook-url>" # Required if ALERT_ON_RELOAD is true
ALERT_ADDITIONAL_INFO: "Triggered by Reloader in staging environment"
7. ⏸️ Pause Deployments
This feature allows you to pause rollouts for a deployment for a specified duration, helping to prevent multiple restarts when several ConfigMaps or Secrets are updated in quick succession.
| Annotation |
Applies To |
Description |
deployment.reloader.stakater.com/pause-period: "5m" |
Deployment |
Pauses reloads for the specified period (e.g., 5m, 1h) |
How it works
- Add the
deployment.reloader.stakater.com/pause-period annotation to your Deployment, specifying the pause duration (e.g., "5m" for five minutes).
- When a watched ConfigMap or Secret changes, Reloader will still trigger a reload event, but if the deployment is paused, the rollout will have no effect until the pause period has elapsed.
- This avoids repeated restarts if multiple resources are updated close together.
Use when
- ✅ Your deployment references multiple ConfigMaps or Secrets that may be updated at the same time.
- ✅ You want to minimize unnecessary rollouts and reduce downtime caused by back-to-back configuration changes.
8. 🔐 CSI Secret Provider Support
Reloader supports the Secrets Store CSI Driver, which allows mounting secrets from external secret stores (like AWS Secrets Manager, Azure Key Vault, HashiCorp Vault) directly into pods.
Unlike Kubernetes Secret objects, CSI-mounted secrets do not always trigger native Kubernetes update events. Reloader solves this by watching CSI status resources and restarting affected workloads when mounted secret versions change.
How it works
When secret rotation is enabled, the Secrets Store CSI Driver updates a Kubernetes resource called: SecretProviderClassPodStatus
This resource reflects the currently mounted secret versions for a pod.
Reloader watches these updates and triggers a rollout when a change is detected.
Prerequisites
- Secrets Store CSI Driver must be installed in your cluster
- Secret rotation enabled in the CSI driver.
- Enable CSI integration in Reloader:
--enable-csi-integration=true
Annotations for CSI-mounted Secrets
| Annotation |
Description |
reloader.stakater.com/auto: "true" |
Global Discovery: Automatically discovers and reloads the workload when any mounted ConfigMap or Secret is updated. |
secretproviderclass.reloader.stakater.com/auto: 'true' |
CSI Discovery: Specifically watches for updates to all SecretProviderClasses used by the workload (CSI driver integration). |
secretproviderclass.reloader.stakater.com/reload: "my-secretproviderclass" |
Targeted Reload: Only reloads the workload when the specifically named SecretProviderClass(es) are updated. |
Reloader monitors changes at the per-secret level by watching the SecretProviderClassPodStatus. Make sure each secret you want to monitor is properly defined with a secretKey in your SecretProviderClass:
apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
name: vault-reloader-demo
namespace: test
spec:
provider: vault
parameters:
vaultAddress: "http://vault.vault.svc:8200"
vaultSkipTLSVerify: "true"
roleName: "demo-role"
objects: |
- objectName: "password"
secretPath: "secret/data/reloader-demo"
secretKey: "password"
Important: Reloader tracks changes to individual secrets (identified by secretKey). If your SecretProviderClass doesn't specify secretKey for each object, Reloader may not detect updates correctly.
Notes & Limitations
Reloader reacts to CSI status changes, not direct updates to external secret stores
Secret rotation must be enabled in the CSI driver for updates to be detected
CSI limitations (such as subPath mounts) still apply and may require pod restarts
If secrets are synced to Kubernetes Secret objects, standard Reloader behavior applies and CSI support may not be required
🚀 Installation
1. 📦 Helm
Reloader can be installed in multiple ways depending on your Kubernetes setup and preference. Below are the supported methods:
helm repo add stakater https://stakater.github.io/stakater-charts
helm repo update
helm install reloader stakater/reloader
➡️ See full Helm configuration in the chart README.
2. 📄 Vanilla Manifests
Apply raw Kubernetes manifests directly:
kubectl apply -f https://raw.githubusercontent.com/stakater/Reloader/master/deployments/kubernetes/reloader.yaml
3. 🧱 Vanilla Kustomize
Use the built-in Kustomize support:
kubectl apply -k https://github.com/stakater/Reloader/deployments/kubernetes
4. 🛠️ Custom Kustomize Setup
You can create your own kustomization.yaml and use Reloader’s as a base:
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- https://github.com/stakater/Reloader/deployments/kubernetes
namespace: reloader
5. ⚖️ Default Resource Requests and Limits
By default, Reloader is deployed with the following resource requests and limits:
resources:
limits:
cpu: 150m
memory: 512Mi
requests:
cpu: 10m
memory: 128Mi
6. ⚙️ Optional runtime configurations
These flags let you customize Reloader's behavior globally, at the Reloader controller level.
1. 🔁 Reload Behavior
| Flag |
Description |
--reload-on-create=true |
Reload workloads when a watched ConfigMap or Secret is created |
--reload-on-delete=true |
Reload workloads when a watched ConfigMap or Secret is deleted |
--auto-reload-all=true |
Automatically reload all workloads unless opted out (auto: "false") |
--reload-strategy=env-vars |
Strategy to use for triggering reload (env-vars or annotations) |
--log-format=json |
Enable JSON-formatted logs for better machine readability |
Reload Strategies
Reloader supports multiple strategies for triggering rolling updates when a watched ConfigMap or Secret changes. You can configure the strategy using the --reload-strategy flag.
| Strategy |
Description |
env-vars (default) |
Adds a dummy environment variable to any container referencing the changed resource (e.g., Deployment, StatefulSet, etc.). This forces Kubernetes to perform a rolling update. |
annotations |
Adds a reloader.stakater.com/last-reloaded-from annotation to the pod template metadata. Ideal for GitOps tools like ArgoCD, as it avoids triggering unwanted sync diffs. |
- The
env-vars strategy is the default and works in most setups.
- The
annotations strategy is preferred in GitOps environments to prevent config drift in tools like ArgoCD or Flux.
- In
annotations mode, a ConfigMap or Secret that is deleted and re-created will still trigger a reload (since previous state is not tracked).
2. 🚫 Resource Filtering
| Flag |
Description |
--resources-to-ignore=configmaps |
Ignore ConfigMaps (only one type can be ignored at a time) |
--resources-to-ignore=secrets |
Ignore Secrets (cannot combine with configMaps) |
--ignored-workload-types=jobs,cronjobs |
Ignore specific workload typ |
Reloader 是一个 Kubernetes 控制器，它会监视 ConfigMap 和 Secret，并自动触发引用这些资源的工作负载滚动重启，包括 Deployment、StatefulSet、DaemonSet 等。