If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/stakater/Reloader shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 6 active contributors
• Distributed ownership (top contributor 42% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live stakater/Reloader repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/stakater/Reloader.

What it runs against: a local clone of stakater/Reloader — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in stakater/Reloader | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of stakater/Reloader. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/stakater/Reloader.git
#   cd Reloader
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of stakater/Reloader and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "stakater/Reloader(\\.git)?\\b" \\
  && ok "origin remote is stakater/Reloader" \\
  || miss "origin remote is not stakater/Reloader (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "internal/pkg/cmd/reloader.go" \\
  && ok "internal/pkg/cmd/reloader.go" \\
  || miss "missing critical file: internal/pkg/cmd/reloader.go"
test -f "internal/pkg/controller/controller.go" \\
  && ok "internal/pkg/controller/controller.go" \\
  || miss "missing critical file: internal/pkg/controller/controller.go"
test -f "internal/pkg/callbacks/rolling_upgrade.go" \\
  && ok "internal/pkg/callbacks/rolling_upgrade.go" \\
  || miss "missing critical file: internal/pkg/callbacks/rolling_upgrade.go"
test -f "go.mod" \\
  && ok "go.mod" \\
  || miss "missing critical file: go.mod"
test -f "internal/pkg/app/app.go" \\
  && ok "internal/pkg/app/app.go" \\
  || miss "missing critical file: internal/pkg/app/app.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/stakater/Reloader"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Reloader is a Kubernetes operator written in Go that automatically triggers rolling restarts of Deployments, StatefulSets, DaemonSets, and DeploymentConfigs whenever their referenced ConfigMaps or Secrets are updated. It solves the fundamental problem that Kubernetes doesn't natively reload workloads when configuration data changes, ensuring applications always run with current credentials, feature flags, and environment configs without manual intervention. Single binary operator deployed as a Kubernetes controller. The codebase is structured as a monolithic Go module (github.com/stakater/Reloader) with Helm charts in deployments/kubernetes/chart/reloader/ for multi-environment deployment. CI/CD driven by GitHub Actions workflows, container images published to Docker Hub, with release automation via .goreleaser.yml.

Platform engineers and DevOps teams managing Kubernetes clusters who need automatic configuration hot-reloading for workloads, particularly in environments using external secret managers (ExternalSecrets, SealedSecrets, cert-manager) or frequent CI/CD deployments where secrets and configs change regularly.

Production-ready and actively maintained. The project has significant GitHub stars, comprehensive CI/CD pipelines across .github/workflows/ (release.yaml, push.yaml, pull_request.yaml), multiple deployment strategies (Helm charts in deployments/kubernetes/chart/reloader/), and supports Kubernetes 1.35.3+ with enterprise versions. Active development visible with Go 1.26.2 compatibility.

Low risk for established Kubernetes environments. Dependencies are well-maintained (k8s.io libraries at 0.35.3, argoproj/argo-rollouts at 1.9.0, prometheus client_golang at 1.23.2). Single maintainer (Stakater org) could be a concern for critical deployments, though the project has multiple adopters. No obvious breaking change warnings visible in version file.

Active development on release automation (.github/workflows/release.yaml, init-branch-release.yaml), Helm chart publishing (push-helm-chart.yaml, release-helm-chart.yaml), and load testing infrastructure (.github/actions/loadtest/). Enterprise edition tracking workflows visible (reloader-enterprise-published.yml, reloader-enterprise-unpublished.yml).

git clone https://github.com/stakater/Reloader.git
cd Reloader
make build
kubectl apply -f deployments/kubernetes/chart/reloader/templates/

Or via Helm: helm repo add stakater https://stakater.github.io/helm-charts && helm install reloader stakater/reloader

Daily commands: Build: make build (see Makefile for exact targets). Deploy locally: kubectl apply -f deployments/kubernetes/chart/reloader/templates/ after building Docker image. For CI: GitHub Actions trigger on push/PR to main branch, building multi-platform images and running load tests via .github/actions/loadtest/action.yml.

• internal/pkg/cmd/reloader.go — Entry point for the Reloader application; defines the CLI command structure and initialization logic that all contributors must understand.
• internal/pkg/controller/controller.go — Core controller logic that watches ConfigMaps/Secrets and triggers rolling upgrades; the heart of the watch-and-reload mechanism.
• internal/pkg/callbacks/rolling_upgrade.go — Implements the rolling upgrade logic for Deployments, StatefulSets, DaemonSets, and DeploymentConfigs; critical for understanding how pods are restarted.
• go.mod — Declares all dependencies including Kubernetes client libraries and OpenShift API; essential for build and dependency management.
• internal/pkg/app/app.go — Application initialization and setup; orchestrates controller creation and manages the lifecycle of the Reloader service.
• internal/pkg/crypto/sha.go — SHA hashing utilities for detecting ConfigMap/Secret changes; fundamental to the change-detection mechanism.
• deployments/kubernetes/chart/reloader/Chart.yaml — Helm chart definition for production deployments; documents the official deployment method and chart metadata.

Add Support for a New Resource Type

1. Define the resource type enum in internal/pkg/constants/enums.go (internal/pkg/constants/enums.go)
2. Add a new case handler in the rolling upgrade callback for your resource type (internal/pkg/callbacks/rolling_upgrade.go)
3. Extend the controller to watch your new resource type by adding a listener in the controller initialization (internal/pkg/controller/controller.go)
4. Add unit tests for the new resource type handling (internal/pkg/callbacks/rolling_upgrade_test.go)
5. Update the ClusterRole to grant permissions for watching/getting the new resource type (deployments/kubernetes/chart/reloader/templates/clusterrole.yaml)

Add a New Alert Channel

1. Create a new alert implementation file in internal/pkg/alerts/ (e.g., teams_alert.go or pagerduty_alert.go) (internal/pkg/alerts/slack_alert.go)
2. Implement the alert interface from internal/pkg/alerts/alert.go (internal/pkg/alerts/alert.go)
3. Register the new alert type in the app initialization logic (internal/pkg/app/app.go)
4. Add environment variable configuration options in the Helm chart values (deployments/kubernetes/chart/reloader/values.yaml)

Add a New CLI Flag or Configuration Option

1. Define the new flag in the Cobra command structure (internal/pkg/cmd/reloader.go)
2. Add the configuration handling in app initialization (internal/pkg/app/app.go)
3. Update the Helm values to support the new configuration option (deployments/kubernetes/chart/reloader/values.yaml)
4. Update the deployment manifest to pass the flag to the container (deployments/kubernetes/chart/reloader/templates/deployment.yaml)

Improve Change Detection Logic

1. Modify or extend the SHA hashing logic for your change detection strategy (internal/pkg/crypto/sha.go)
2. Add tests for the new hashing behavior (internal/pkg/crypto/sha_test.go)
3. Integrate the new change detection into the controller's event handling (internal/pkg/controller/controller.go)

• Go 1.26.2 — Kubernetes ecosystem standard; enables efficient concurrent goroutine-based watchers and lightweight container images.
• Kubernetes client-go (k8s.io/client-go) — Official Kubernetes Go client; provides native support for watching ConfigMaps, Secrets, and triggering rolling upgrades.
• Cobra CLI framework (spf13/cobra) — Industry-standard CLI library for Go; simplifies command-line argument parsing and help documentation.
• OpenShift API (openshift/api and openshift/client-go) — Extends Kubernetes support to OpenShift DeploymentConfigs; essential for organizations using Red Hat OpenShift.
• Argo Rollouts (argoproj/argo-rollouts) — Enables advanced deployment strategies (canary, blue-green) for safer rolling upgrades.
• Prometheus client (prometheus/client_golang) — Exposes operational metrics for monitoring Reloader performance and deployment events.
• Helm — Standard package manager for Kubernetes; simplifies multi-environment deployment and configuration management.

• SHA-based change detection for ConfigMap/Secret mutations

  • Why: Avoids false positives from metadata-only changes and provides a lightweight, deterministic change signal.
  • Consequence: Does not detect fine-grained field-level changes; entire resource hash is compared, which could miss partial updates.

• Rolling upgrade via Pod template annotation injection

  • Why: Leverages Kubernetes' native rolling update mechanism without requiring custom webhooks or admission controllers.
  • Consequence: Annotation-based triggering is less granular than webhook-based solutions; relies on Kubernetes built-in behavior.

• Cluster-scoped RBAC permissions (ClusterRole)

  • Why: Simplifies multi-namespace deployments and allows watching resources across the entire cluster.
  • Consequence: Grants broad permissions; requires careful RBAC governance in multi-tenant clusters.

• Synchronous change detection and rolling upgrade

  • Why: Ensures deterministic ordering and immediate response to configuration changes.
  • Consequence: No queuing or rate-limiting; burst changes could overwhelm the controller or cause cascading deployments.

• Does not validate ConfigMap/Secret content; only detects changes and triggers rollouts.
• Does not provide authentication/authorization; relies on Kubernetes RBAC.
• Does not implement admission control or webhook validation; operates as a post-deployment watch controller.
• Does not support real-time, sub-second update detection; relies on Kubernetes watch event latency (~100ms–1s).
• Does not manage secret encryption or rotation; integrates with external secret management (Sealed Secrets, HashiCorp Vault) via CSI drivers.

RBAC-heavy: The operator requires ClusterRole with watch, get, list permissions on ConfigMaps, Secrets, and workload resources (deployments, statefulsets, daemonsets, deploymentconfigs); check deployments/kubernetes/chart/reloader/templates/clusterrole.yaml to ensure proper permissions. Namespace scoping: Default deployment may be cluster-wide; multi-tenancy requires separate instances or careful RBAC boundaries. CSI-mounted secrets: The code references sigs.k8s.io/secrets-store-csi-driver v1.5.5 but requires explicit opt-in via annotations. Version lock: Kubernetes 0.35.3 client APIs are tightly coupled; upgrading requires testing against target Kubernetes version.

• Kubernetes Informer Pattern — Reloader uses informers from k8s.io/client-go to efficiently watch ConfigMap and Secret changes; understanding caching and resync intervals is critical for tuning controller responsiveness
• Pod Disruption Budget (PDB) Constraints — Rolling updates triggered by Reloader must respect PDB policies; improper handling can cause cascading failures in multi-replica workloads
• Workload Reconciliation Loop — Reloader implements the operator pattern's core loop: watch → detect change → trigger rollout; understanding the reconciliation state machine prevents infinite loops or missed updates
• Secret and ConfigMap Versioning Hash — Reloader likely injects a hash of config/secret contents into pod annotations to force restarts; understanding hash collision risks and update atomicity is critical for reliability
• OpenShift DeploymentConfig — Reloader explicitly supports DeploymentConfigs (via openshift/api imports) alongside standard Kubernetes Deployments; rollout semantics differ from native Deployment rolling updates
• Argo Rollout Custom Resource — Reloader integrates with ArgoCd Rollouts (argoproj/argo-rollouts v1.9.0) for canary/blue-green deployments; triggering rollouts requires understanding Argo's Rollout CRD instead of standard Deployment spec
• CSI Secret Driver Mounting — Reloader references sigs.k8s.io/secrets-store-csi-driver for detecting mounted secrets that don't appear in Pod env vars; requires understanding of volume mount tracking and CSI driver lifecycle

• jimmidyson/configmap-reload — Alternative lightweight sidecar-based approach; watches ConfigMaps and triggers application reloads via webhooks rather than pod restarts
• stakater/Forecastle — Same maintainer (Stakater); complements Reloader in Kubernetes dashboards and service discovery
• argoproj-labs/argocd-image-updater — Works alongside Reloader in GitOps workflows; updates image references while Reloader handles secret/config rollouts
• external-secrets/external-secrets — Common upstream for Reloader; creates/updates Secrets that Reloader then watches for changes
• sealed-secrets/sealed-secrets — Common upstream for Reloader; encrypts Secrets that Reloader then detects and rolls out to workloads

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for Argo Rollouts support in reloader

The repo declares dependency on github.com/argoproj/argo-rollouts v1.9.0 and supports ArgoCD rollouts alongside Deployments, StatefulSets, and DaemonSets, but there are no visible test files in deployments/kubernetes/chart/reloader/tests/ (only deployment_test.yaml exists). This is a critical gap for a production controller that claims to support rolling upgrades across multiple resource types.

• [ ] Create deployments/kubernetes/chart/reloader/tests/argo-rollouts_test.yaml with test cases for ArgoRollouts detection and pod restart
• [ ] Add unit tests in cmd/ or pkg/ (structure needed) covering argorollouts.go watch/trigger logic
• [ ] Document the test execution in a new Testing section of deployments/kubernetes/chart/reloader/README.md

Add comprehensive example manifests for ConfigMap/Secret watching use cases

The deployments/kubernetes/manifests/ directory contains only RBAC and deployment boilerplate, but no example ConfigMap or Secret resources with reloader annotations. New users can't easily understand how to annotate their resources. This is a gap for adoption and onboarding.

• [ ] Create deployments/kubernetes/manifests/example-configmap-with-reloader.yaml showing reloader.stakater.com/match annotation usage
• [ ] Create deployments/kubernetes/manifests/example-secret-with-reloader.yaml with corresponding Deployment that consumes it
• [ ] Create deployments/kubernetes/manifests/example-openshift-deploymentconfig.yaml for OpenShift users (since openshift/api is a direct dependency)
• [ ] Update deployments/kubernetes/chart/reloader/README.md with links and brief explanation of each example

Add Prometheus metrics documentation and example ServiceMonitor configuration

The repo includes prometheus/client_golang v1.23.2 as a dependency and the Helm chart has servicemonitor.yaml and podmonitor.yaml templates, but there's no documentation explaining what metrics are exported or how to configure them. This blocks monitoring setup for operators.

• [ ] Create docs/MONITORING.md documenting exported metrics (e.g., reloader_pods_reloaded_total, reloader_configmap_changes_detected) with sample queries
• [ ] Add example deployments/kubernetes/manifests/servicemonitor.yaml showing a concrete Prometheus ServiceMonitor configuration for Reloader
• [ ] Update deployments/kubernetes/chart/reloader/README.md Values section with brief explanation of podmonitor and servicemonitor options
• [ ] Reference the new MONITORING.md from the main README.md

• Add test coverage for ConfigMap delta detection in the watcher (look for Watch or Informer implementations in the codebase); mutation testing tools could verify edge cases like empty-to-nonempty transitions
• Document supported annotation syntax with examples for each workload type (Deployment, StatefulSet, DaemonSet, DeploymentConfig, ArgoRollout, CronJob) in deployments/kubernetes/chart/reloader/README.md — currently READme shows flowchart but lacks detailed label/annotation reference
• Add Prometheus metric for 'time-to-rollout' (delay between ConfigMap change detection and actual Pod restart) to enable SLO monitoring; integrate into existing prometheus metrics setup in github.com/prometheus/client_golang

• High · Outdated Go Version — go.mod. The project specifies Go 1.26.2 in go.mod, which appears to be a future/unreleased version. This is unusual and may indicate a configuration error or testing with pre-release Go versions. Using non-standard Go versions can introduce compatibility issues and may not receive security patches. Fix: Use a stable, released Go version (e.g., 1.21.x, 1.22.x, or latest stable LTS). Verify the Go version is appropriate for production use.
• High · Insecure HTTP Library Dependency — go.mod (github.com/parnurzeal/gorequest v0.3.0). The dependency 'github.com/parnurzeal/gorequest v0.3.0' is a deprecated HTTP client library that is no longer maintained. It has known security vulnerabilities and is not recommended for production use. Fix: Replace gorequest with the standard 'net/http' package or a maintained alternative like 'github.com/go-resty/resty' or 'github.com/hashicorp/go-retryablehttp'.
• Medium · Potential Security Header Misconfiguration — docs-nginx.conf. The presence of 'docs-nginx.conf' suggests nginx configuration for documentation serving. Without reviewing the file content, nginx instances commonly suffer from missing security headers (X-Frame-Options, X-Content-Type-Options, CSP, HSTS, etc.). Fix: Ensure the nginx configuration includes security headers: add_header X-Frame-Options 'SAMEORIGIN'; add_header X-Content-Type-Options 'nosniff'; add_header X-XSS-Protection '1; mode=block'; add_header Strict-Transport-Security 'max-age=31536000; includeSubDomains' always; add_header Content-Security-Policy "default-src 'self'";
• Medium · Multi-stage Dockerfile with Build Arguments — Dockerfile. The Dockerfile uses build arguments (GOPROXY, GOPRIVATE) that could potentially be exposed in image layers or logs. Additionally, the builder image is parameterized but defaults to golang:1.26.2, which may not be from a trusted source or pinned to a specific secure version. Fix: 1) Pin base images to specific digests (e.g., golang:1.21@sha256:...) rather than tags. 2) Use --secret flag for sensitive build arguments. 3) Avoid logging build arguments. 4) Consider using distroless or alpine-based final images for reduced attack surface.
• Medium · Missing RBAC Principle of Least Privilege Analysis — deployments/kubernetes/manifests/clusterrole.yaml, deployments/kubernetes/chart/reloader/templates/clusterrole.yaml. While RBAC manifests exist in deployments/kubernetes/manifests/, the clusterrole.yaml likely grants broad permissions for ConfigMap and Secret watching. Without reviewing the specific permissions, this could violate principle of least privilege. Fix: Audit and restrict ClusterRole permissions to only necessary actions (e.g., get, watch, list for specific resource types in specific namespaces). Use RBAC best practices and consider namespace-scoped roles where possible.
• Medium · Unverified Third-party Dependencies — go.mod. Multiple OpenShift and Argo Rollouts dependencies are used (github.com/argoproj/argo-rollouts, github.com/openshift/api, github.com/openshift/client-go) but their security posture is not independently verified in this analysis. Fix: 1) Run 'go mod graph' and 'go mod audit' regularly. 2) Use 'govulncheck' to check for known vulnerabilities. 3) Pin dependency versions and monitor security advisories. 4) Consider using a software composition analysis (SCA) tool.
• Low · Hardcoded Strip Flags in Build — Dockerfile (go build ldflags). The Dockerfile uses '-s -w' flags in ldflags which strips symbols from the binary. While this reduces binary size, it also removes debugging information which could complicate incident response and security analysis. Fix: Consider keeping debug symbols in development/staging builds and

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.