Reloader

<p align="center"> <img src="assets/web/reloader.jpg" alt="Reloader" width="40%"/> </p>

🔁 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.

🚀 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.

⚡ 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.

🏢 Enterprise Version

Stakater offers an enterprise-grade version of Reloader with:

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

Contact sales@stakater.com for info about Reloader Enterprise.

🧩 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

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.

3. 🎯 Targeted Reload (Match + Search Annotations)

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

1. Referenced by the workload
2. 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

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.)

Use when

1. ✅ 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".
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.

⛔ 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:

1. You're using GitOps and want to avoid drift
2. You want