From 5c8bc15e60f2a1aa857a7794356aa75fde4ce077 Mon Sep 17 00:00:00 2001 From: mr-forust Date: Tue, 6 Oct 2026 16:14:04 +0200 Subject: [PATCH] docs(reloader): describe workload opt-in and reload policy --- README.md | 2 +- docs/repository-review.md | 15 +++++++++++ reloader/README.md | 57 ++++++++++++++++++++++++++++++++++----- 3 files changed, 66 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 6ff1bef..4829eef 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,7 @@ service is currently healthy or running. | [Shared PostgreSQL](postgres/README.md) | Kubernetes + Compose | Kubernetes | | [Monitoring stack](prometheus-stack/README.md) | Kubernetes + Compose | Kubernetes | | [RackPeek](rackpeek/README.md) | Kubernetes + Compose | Kubernetes | -| [Reloader](reloader/README.md) | Kubernetes / Helm | Manual | +| [Reloader](reloader/README.md) | Kubernetes / Helm | Kubernetes | | [Renovate](renovate/README.md) | Kubernetes + Compose | Kubernetes | | [SearXNG](searxng/README.md) | Kubernetes + Compose | Manual | | [Media stack](streaming/README.md) | Compose + Kubernetes routing | Compose, Kubernetes | diff --git a/docs/repository-review.md b/docs/repository-review.md index 28e0ba9..937c573 100644 --- a/docs/repository-review.md +++ b/docs/repository-review.md @@ -134,3 +134,18 @@ not run. Runtime tests use fixtures and mocks, not production credentials. Live checks read workload metadata, storage policies, chart versions, and container state only. They did not read Secret contents or change services. + +## Reloader follow-up + +`fix/reloader-integration` adds the active marker and opt-in annotations to 28 +application Deployments/StatefulSets that consume runtime ConfigMaps or Secrets. +It corrects AdGuard's misplaced pod-template annotation. The Helm settings use +annotation-based reloads, keep global auto-reload disabled, and ignore Jobs and +CronJobs. PostgreSQL workloads are excluded because their credential variables +and init scripts are only effective on an empty data directory. + +The controller was already running on workstation when inspected. Its live +configuration is unchanged by the branch: merge and deploy the integration to +apply the new policy and application annotations. Configuration reload behavior +was checked against the pinned chart, with Helm rendering and manifest validation; +no production configuration was changed to provoke a test restart. diff --git a/reloader/README.md b/reloader/README.md index 2ac9b54..a8a2db1 100644 --- a/reloader/README.md +++ b/reloader/README.md @@ -1,13 +1,56 @@ # Reloader -Helm settings for restarting workloads when referenced configuration changes. +Restarts opted-in workloads when the ConfigMaps or Secrets they consume change. +The deploy workflow upgrades the `reloader` Helm release in namespace `reloader`; +`k8s/active` enables it. The chart version is pinned in `deploy-lib.sh`. -The deploy library knows the `reloader` Helm release and the values file here, -but there is no `k8s/active` marker, so it is not upgraded automatically. +## Workload integration -Reloader only acts on workloads configured for it. A ConfigMap mounted with -`subPath` does not update inside an existing container by itself. Verify that the -application restarted after a configuration change rather than assuming an -apply updated the running process. +Put this annotation on the Deployment or StatefulSet metadata: + +```yaml +metadata: + annotations: + reloader.stakater.com/auto: "true" +``` + +The annotation belongs to the workload, not `spec.template.metadata`. +Reloader discovers references in environment variables and mounted volumes. +This covers startup-only settings and ConfigMaps or Secrets mounted with `subPath`. +See the [upstream usage guide](https://github.com/stakater/Reloader/blob/v1.4.22/README.md#usage). + +The application manifests opt in 28 workloads, including AdGuard's TLS files, +NetBird, both NetBox processes, EDU bots, and the password-protected Valkey servers. +Inactive services have the same annotations ready for later activation. + +## Controller policy + +The controller watches all namespaces but only restarts annotated workloads. +It uses the `annotations` reload strategy, so changes trigger a pod-template +annotation rather than injecting extra environment variables. + +Jobs and CronJobs are excluded: their next execution reads current configuration. +PostgreSQL is intentionally not opted in. Its password variables and init scripts +apply to first initialization; restarting an existing database does not rotate +roles or rerun those scripts. Rotate database credentials with SQL and update the +clients' Secrets together. + +Helm-managed monitoring components already have their own configuration reload +paths; Traefik watches its file-provider configuration. They are not globally +opted in. The controller does not react to files in PVCs or changes to external +services unless a watched ConfigMap or Secret changes. + +## Verify + +```sh +kubectl -n reloader rollout status deployment/reloader-reloader +kubectl -n reloader logs deployment/reloader-reloader --since=10m +kubectl -n netbird get deployment netbird-server-deployment \ + -o jsonpath='{.metadata.annotations.reloader\.stakater\.com/auto}' +``` + +A changed configuration can briefly interrupt a single-replica service, especially +one using `Recreate`. Installing annotations does not validate the configuration +or migrate database data. Keep changes to shared Secrets coordinated across consumers. See the [repository README](../README.md) for deployment selection.