Repository files navigation

Reloader is a Kubernetes controller that automatically triggers rollouts of workloads (like Deployments, StatefulSets, and more) whenever referencedSecrets orConfigMaps are updated.

In a traditional Kubernetes setup, updating aSecret orConfigMap 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.

• ✅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.

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 likeExternalSecret,SealedSecret, orCertificate fromcert-manager can create or manage KubernetesSecrets — but they can also be created manually or delivered through GitOps workflows.
• Secrets andConfigMaps 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.

Follow any of thisinstallation options.

To enable automatic reload for a Deployment:

apiVersion:apps/v1kind:Deploymentmetadata:name:my-appannotations:reloader.stakater.com/auto:"true"spec:template:metadata:labels:app:my-appspec:containers:        -name:appimage:your-imageenvFrom:            -configMapRef:name:my-config            -secretRef:name:my-secret

This tells Reloader to watch theConfigMap andSecret referenced in this deployment. When either is updated, it will trigger a rollout.

Stakater offers an enterprise-grade version of Reloader with:

1. SLA-backed support
2. Certified images
3. Private Slack support

Contactsales@stakater.com for info about Reloader Enterprise.

Reloader supports multiple annotation-based controls to let youcustomize when and how your Kubernetes workloads are reloaded upon changes inSecrets orConfigMaps.

Kubernetes does not trigger pod restarts when a referencedSecret orConfigMap 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:

• Reloadall resources by default
• Restrict reloads to onlySecrets or onlyConfigMaps
• Watch onlyspecific resources
• Useopt-in via tagging (search +match)
• Exclude workloads you don’t want to reload

Use these annotations to automatically restart the workload when referencedSecrets orConfigMaps change.

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.

1. ✅ This is useful in tightly scoped scenarios where config is shared but reloads are only relevant in certain cases.
2. ✅ Use this when you know exactly which resource(s) matter and want to avoid auto-discovery or searching altogether.

This pattern allows fine-grained reload control — workloads only restart if the Secret/ConfigMap is both:

1. Referenced by the workload
2. Explicitly annotated withmatch: true

1. The workload must have:reloader.stakater.com/search: "true"
2. The ConfigMap or Secret must have:reloader.stakater.com/match: "true"
3. The resource (ConfigMap or Secret) must also be referenced in the workload (via env,volumeMount, etc.)

1. ✅ You want to reload a workload only if it references a ConfigMap or Secret that has been explicitly tagged withreloader.stakater.com/match: "true".
2. ✅ Use this when you want full control over which shared or system-wide resources trigger reloads. Great in multi-tenant clusters or shared configs.

When you need to prevent specific ConfigMaps or Secrets from triggering any reloads, use the ignore annotation on the resource itself:

apiVersion:v1kind:ConfigMap# or Secretmetadata:name:my-configannotations:reloader.stakater.com/ignore:"true"

This instructs Reloader to skip all reload logic for that resource across all workloads.

By default, Reloader uses therollout strategy — it updates the pod template to trigger a new rollout. This works well in most cases, but it can cause problems if you're using GitOps tools like ArgoCD, which detect this as configuration drift.

To avoid that, you can switch to therestart strategy, which simply restarts the pod without changing the pod template.

metadata:annotations:reloader.stakater.com/rollout-strategy:"restart"

✅ Userestart if:

1. You're using GitOps and want to avoid drift
2. You want a quick restart without changing the workload spec
3. Your platform restricts metadata changes

• reloader.stakater.com/auto andreloader.stakater.com/searchcannot be used together — theauto annotation takes precedence.
• If bothauto 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.
• Settingreloader.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 haveauto: "true" unless they explicitly set it to"false".
  • Missing or unrecognized annotation values are treated as"false".

Reloader can optionallysend alerts whenever it triggers a rolling upgrade for a workload (e.g.,Deployment,StatefulSet, etc.).

These alerts are sent to a configuredwebhook endpoint, which can be a generic receiver or services like Slack, Microsoft Teams or Google Chat.

To enable this feature, update thereloader.env.secret section in yourvalues.yaml (when installing via Helm):

reloader: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 trueALERT_ADDITIONAL_INFO:"Triggered by Reloader in staging environment"

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.

1. Add thedeployment.reloader.stakater.com/pause-period annotation to your Deployment, specifying the pause duration (e.g.,"5m" for five minutes).
2. 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.
3. This avoids repeated restarts if multiple resources are updated close together.

1. ✅ Your deployment references multiple ConfigMaps or Secrets that may be updated at the same time.
2. ✅ You want to minimize unnecessary rollouts and reduce downtime caused by back-to-back configuration changes.

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-chartshelm repo updatehelm install reloader stakater/reloader

➡️ See full Helm configuration in thechart README.

Apply raw Kubernetes manifests directly:

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

Use the built-in Kustomize support:

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

You can create your ownkustomization.yaml and use Reloader’s as a base:

apiVersion:kustomize.config.k8s.io/v1beta1kind:Kustomizationresources:  -https://github.com/stakater/Reloader/deployments/kubernetesnamespace:reloader

By default, Reloader is deployed with the following resource requests and limits:

resources:limits:cpu:150mmemory:512Mirequests:cpu:10mmemory:128Mi

These flags let you customize Reloader's behavior globally, at the Reloader controller level.

Reloader supports multiple strategies for triggering rolling updates when a watchedConfigMap orSecret changes. You can configure the strategy using the--reload-strategy flag.

• Theenv-vars strategy is the default and works in most setups.
• Theannotations strategy is preferred inGitOps environments to prevent config drift in tools like ArgoCD or Flux.
• Inannotations mode, aConfigMap orSecret that is deleted and re-created will still trigger a reload (since previous state is not tracked).

⚠️ Note:

Onlyone resource type can be ignored at a time.Trying to ignorebothconfigmaps andsecrets will cause an error in Reloader.✅Workaround: Scale the Reloader deployment to0 replicas if you want to disable it completely.

💡 Workload Type Examples:

# Ignore only Jobs--ignored-workload-types=jobs# Ignore only CronJobs--ignored-workload-types=cronjobs# Ignore both (comma-separated)--ignored-workload-types=jobs,cronjobs

🔧 Use Case: Ignoring workload types is useful when you don't want certain types of workloads to be automatically reloaded.

These flags allow you to redefine annotation keys used in your workloads or resources:

Reloader is compatible with Kubernetes >= 1.19

The Reloader documentation can be viewed fromthe doc site. The doc source is in thedocs folder.

File a GitHubissue.

Join and talk to us on Slack for discussing Reloader:

Please use theissue tracker to report any bugs or file feature requests.

1. Deploy Reloader
2. Runokteto up to activate your development container
3. make build
4. ./Reloader

PRs are welcome. In general, we follow the "fork-and-pull" Git workflow:

1. Fork the repo on GitHub
2. Clone the project to your own machine
3. Commit changes to your own branch
4. Push your work back up to your fork
5. Submit aPull request so that we can review your changes

NOTE: Be sure to merge the latest from "upstream" before making a pull request!

Repository GitHub releases: As requested by the community inissue 685, Reloader is now based on a manual release process. Releases are no longer done on every merged PR to the main branch, but manually on request.

To make a GitHub release:

1. Code owners create a release branchrelease-vX.Y.Z frommaster
2. Code owners runInit Release workflow to automatically generate version and manifests on the release branch
   • Set theTARGET_BRANCH parameter to release branch i.e.release-vX.Y.Z
   • Set theTARGET_VERSION to release version without 'v' i.e.X.Y.Z
3. A PR is created to bump the image version on the release branch, example:PR-798
4. Code owners create a GitHub release with tagvX.Y.Z and target branchrelease-vX.Y.Z, which triggers creation of images
5. Code owners create another branch frommaster and bump the helm chart version as well as Reloader image version.
   • Code owners create a PR withrelease/helm-chart label, example:PR-846

Repository git tagging: Push to the main branch will create a merge-image and merge-tag namedmerge-${{ github.event.number }}, for examplemerge-800 when pull request number 800 is merged.

View thereleases page to see what has changed in each release.

Apache2 ©Stakater

Reloader is maintained byStakater. Like it? Please let us know athello@stakater.com

Seeour other projects or contact us in case of professional services and queries onhello@stakater.com