Repository files navigation

We would like to watch if some change happens inConfigMap and/orSecret; then perform a rolling upgrade on relevantDeploymentConfig,Deployment,Daemonset,Statefulset andRollout

Reloader can watch changes inConfigMap andSecret and do rolling upgrades on Pods with their associatedDeploymentConfigs,Deployments,DaemonsetsStatefulsets andRollouts.

Reloader is available in two different versions:

1. Open Source Version
2. Enterprise Version, which includes:
   • SLA (Service Level Agreement) for support and unique requests
   • Slack support
   • Certified images

Contactsales@stakater.com for info about Reloader Enterprise.

Reloader is compatible with Kubernetes >= 1.19

You have aDeployment calledfoo and aConfigMap and/or aSecret either mounted as a volume or defined as a environment variable. TheConfigMap andSecret can be named whatever, but for the sake of this example, lets refer to theConfigMap asfoo-configmap and the secret asfoo-secret.

Add the annotation to the main metadata of yourDeployment. By default this would bereloader.stakater.com/auto.

kind:Deploymentmetadata:name:fooannotations:reloader.stakater.com/auto:"true"spec:template:metadata:

This will discover deploymentconfigs/deployments/daemonsets/statefulset/rollouts/cronjobs/jobs automatically wherefoo-configmap orfoo-secret is being used either via environment variable or from volume mount. And it will perform rolling upgrade on related pods whenfoo-configmap orfoo-secretare updated.

You can filter it by the type of monitored resource and use typed versions ofauto annotation. If you want to discover changes only in mountedSecrets and ignore changes inConfigMaps, addsecret.reloader.stakater.com/auto annotation instead. Analogously, you can useconfigmap.reloader.stakater.com/auto annotation to look for changes in mountedConfigMap, changes in any of mountedSecrets will not trigger a rolling upgrade on related pods.

You can also restrict this discovery to onlyConfigMap orSecret objects thatare tagged with a special annotation. To take advantage of that, annotateyour deploymentconfigs/deployments/daemonsets/statefulset/rollouts/cronjobs/jobs like this:

kind:Deploymentmetadata:annotations:reloader.stakater.com/search:"true"spec:template:

and Reloader will trigger the rolling upgrade upon modification of anyConfigMap orSecret annotated like this:

kind:ConfigMapmetadata:annotations:reloader.stakater.com/match:"true"data:key:value

provided the secret/configmap is being used in an environment variable, or avolume mount.

Please note thatreloader.stakater.com/search andreloader.stakater.com/auto do not work together. If you have thereloader.stakater.com/auto: "true" annotation on your deployment, then itwill always restart upon a change in configmaps or secrets it uses, regardlessof whether they have thereloader.stakater.com/match: "true" annotation ornot.

Similarly,reloader.stakater.com/auto and its typed version (secret.reloader.stakater.com/auto orconfigmap.reloader.stakater.com/auto) do not work together. If you have both annotations in your deployment, then only one of them needs to be true to trigger the restart. For example, having bothreloader.stakater.com/auto: "true" andsecret.reloader.stakater.com/auto: "false" or bothreloader.stakater.com/auto: "false" andsecret.reloader.stakater.com/auto: "true" will restart upon a change in a secret it uses.

We can also specify a specific configmap or secret which would trigger rolling upgrade only upon change in our specified configmap or secret, this way, it will not trigger rolling upgrade upon changes in all configmaps or secrets used in adeploymentconfig,deployment,daemonset,statefulset,rollout,cronJob orjob.To do this either set the auto annotation to"false" (reloader.stakater.com/auto: "false") or remove it altogether, and use annotations forConfigmap orSecret.

It's also possible to enable auto reloading for all resources, by setting the--auto-reload-all flag.In this case, all resources that do not have the auto annotation (or its typed version) set to"false", will be reloaded automatically when their Configmaps or Secrets are updated.Notice that setting the auto annotation to an undefined value counts as false as-well.

To perform rolling upgrade when change happens only on specific configmaps use below annotation.

For aDeployment calledfoo have aConfigMap calledfoo-configmap. Then add this annotation to main metadata of yourDeployment

kind:Deploymentmetadata:annotations:configmap.reloader.stakater.com/reload:"foo-configmap"spec:template:metadata:

Use comma separated list to define multiple configmaps.

kind:Deploymentmetadata:annotations:configmap.reloader.stakater.com/reload:"foo-configmap,bar-configmap,baz-configmap"spec:template:metadata:

To perform rolling upgrade when change happens only on specific secrets use below annotation.

For aDeployment calledfoo have aSecret calledfoo-secret. Then add this annotation to main metadata of yourDeployment

kind:Deploymentmetadata:annotations:secret.reloader.stakater.com/reload:"foo-secret"spec:template:metadata:

Use comma separated list to define multiple secrets.

kind:Deploymentmetadata:annotations:secret.reloader.stakater.com/reload:"foo-secret,bar-secret,baz-secret"spec:template:metadata:

• Reloader also supportssealed-secrets.Here are the steps to use sealed-secrets with Reloader.
• Forrollouts Reloader simply triggers a change is up to you how you configure therollout strategy.
• reloader.stakater.com/auto: "true" will only reload the pod, if the configmap or secret is used (as a volume mount or as an env) inDeploymentConfigs/Deployment/Daemonsets/Statefulsets/CronJobs/Jobs
• secret.reloader.stakater.com/reload orconfigmap.reloader.stakater.com/reload annotation will reload the pod upon changes in specified configmap or secret, irrespective of the usage of configmap or secret.
• you may override the auto annotation with the--auto-annotation flag
• you may override the secret typed auto annotation with the--secret-auto-annotation flag
• you may override the configmap typed auto annotation with the--configmap-auto-annotation flag
• you may override the search annotation with the--auto-search-annotation flagand the match annotation with the--search-match-annotation flag
• you may override the configmap annotation with the--configmap-annotation flag
• you may override the secret annotation with the--secret-annotation flag
• you may want to prevent watching certain namespaces with the--namespaces-to-ignore flag
• you may want to watch only a set of namespaces with certain labels by using the--namespace-selector flag
• you may want to watch only a set of secrets/configmaps with certain labels by using the--resource-label-selector flag
• you may want to prevent watching certain resources with the--resources-to-ignore flag
• you can configure logging in JSON format with the--log-format=json option
• you can configure the "reload strategy" with the--reload-strategy=<strategy-name> option (details below)
• you can configure rollout reload strategy withreloader.stakater.com/rollout-strategy annotation,restart orrollout values are available (defaults torollout)

Reloader supports multiple "reload" strategies for performing rolling upgrades to resources. The following list describes them:

• env-vars: When a trackedconfigMap/secret is updated, this strategy attaches a Reloader specific environment variable to any containers referencing the changedconfigMap orsecret on the owning resource (e.g.,Deployment,StatefulSet, etc.). This strategy can be specified with the--reload-strategy=env-vars argument. Note: This is the default reload strategy.
• annotations: When a trackedconfigMap/secret is updated, this strategy attaches areloader.stakater.com/last-reloaded-from pod template annotation on the owning resource (e.g.,Deployment,StatefulSet, etc.). This strategy is useful when using resource syncing tools like ArgoCD, since it will not cause these tools to detect configuration drift after a resource is reloaded. Note: Since the attached pod template annotation only tracks the last reload source, this strategy will reload any tracked resource should itsconfigMap orsecret be deleted and recreated. This strategy can be specified with the--reload-strategy=annotations argument.

You can deploy Reloader by following methods:

You can apply vanilla manifests by changingRELEASE-NAME placeholder provided in manifest with a proper value and apply it by running the command given below:

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

By default, Reloader gets deployed indefault namespace and watches changessecrets andconfigmaps in all namespaces. Additionally, in the default Reloader deployment, the following resource limits and requests are set:

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

Reloader can be configured to ignore the resourcessecrets andconfigmaps by passing the following arguments (spec.template.spec.containers.args) to its container:

Note: At one time only one of these resource can be ignored, trying to do it will cause error in Reloader. Workaround for ignoring both resources is by scaling down the Reloader pods to0.

Reloader can be configured to only watch secrets/configmaps with one or more labels using the--resource-label-selector parameter. Supported operators are!, in, notin, ==, =, !=, if no operator is found the 'exists' operator is inferred (i.e. key only). Additional examples of these selectors can be found in theKubernetes Docs.

Note: The old: delimited key value mappings are deprecated and if provided will be translated tokey=value. Likewise, if a wildcard value is provided (e.g.key:*) it will be translated to the standalonekey which checks for key existence.

These selectors can be combined, for example with:

--resource-label-selector=reloader=enabled,key-exists,another-label in (value1,value2,value3)

Only configmaps or secrets labeled like the following will be watched:

kind:ConfigMapapiVersion:v1metadata:labels:reloader:enabledkey-exists:yesanother-label:value1

Reloader can be configured to only watch namespaces labeled with one or more labels using the--namespace-selector parameter. Supported operators are!, in, notin, ==, =, !=, if no operator is found the 'exists' operator is inferred (i.e. key only). Additional examples of these selectors can be found in theKubernetes Docs.

Note: The old: delimited key value mappings are deprecated and if provided will be translated tokey=value. Likewise, if a wildcard value is provided (e.g.key:*) it will be translated to the standalonekey which checks for key existence.

These selectors can be combined, for example with:

--namespace-selector=reloader=enabled,test=true

Only namespaces labeled as below would be watched and eligible for reloads:

kind:NamespaceapiVersion:v1metadata:labels:reloader:enabledtest:true

You can also apply the vanilla manifests by running the following command

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

Similarly to vanilla manifests get deployed indefault namespace and watches changessecrets andconfigmaps in all namespaces.

You can write your ownkustomization.yaml using ours as a 'base' and write patches to tweak the configuration.

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

Alternatively if you have configured helm on your cluster, you can add Reloader to helm from our public chart repository and deploy it via helm using below-mentioned commands. Followthis guide, in case you have trouble migrating Reloader from Helm2 to Helm3.

helm repo add stakater https://stakater.github.io/stakater-chartshelm repo updatehelm install stakater/reloader# For helm3 add --generate-name flag or set the release namehelm install {{RELEASE_NAME}} stakater/reloader -n {{NAMESPACE}} --set reloader.watchGlobally=false# By default, Reloader watches in all namespaces. To watch in single namespace, set watchGlobally=falsehelm install stakater/reloader --set reloader.watchGlobally=false --namespacetest --generate-name# Install Reloader in `test` namespace which will only watch `Deployments`, `Daemonsets` `Statefulsets` and `Rollouts` in `test` namespace.

helm uninstall {{RELEASE_NAME}} -n {{NAMESPACE}}

• BothnamespaceSelector &resourceLabelSelector can be used together. If they are then both conditions must be met for the configmap or secret to be eligible to trigger reload events. (e.g. If a configmap matchesresourceLabelSelector butnamespaceSelector does not match the namespace the configmap is in, it will be ignored).
• At one time only one of the resourcesignoreConfigMaps orignoreSecrets can be ignored, trying to do both will cause error in helm template compilation
• Reloading of OpenShift (DeploymentConfig) and/or ArgoRollouts has to be enabled explicitly because it might not be always possible to use it on a cluster with restricted permissions
• isOpenShift Recent versions of OpenShift (tested on 4.13.3) require the specified user to be in anuid range which is dynamically assigned by the namespace. The solution is to unset the runAsUser variable viadeployment.securityContext.runAsUser=null and let OpenShift assign it at install
• reloadOnCreate controls how Reloader handles secrets being added to the cache for the first time. IfreloadOnCreate is set to true:
  1. Configmaps/secrets being added to the cache will cause Reloader to perform a rolling update of the associated workload
  2. When applications are deployed for the first time, Reloader will perform a rolling update of the associated workload
  3. If you are running Reloader in HA mode all workloads will have a rolling update performed when a new leader is elected
• reloadOnDelete controls how Reloader handles secrets being deleted. IfreloadOnDelete is set to true:
  1. Configmaps/secrets being deleted will cause Reloader to perform a rolling update of the associated workload
• serviceMonitor will be removed in future releases of Reloader in favour of Pod monitor
• IfreloadOnCreate is set to false:
  1. Updates to configmaps/secrets that occur while there is no leader will not be picked up by the new leader until a subsequent update of the configmap/secret occurs
  2. In the worst case the window in which there can be no leader is 15s as this is the LeaseDuration
• IfreloadOnDelete is set to false:
  1. Deleting of configmaps/secrets has no effect to pods that references these resources.
• By default,reloadOnCreate,reloadOnDelete andsyncAfterRestart are all set to false. All need to be enabled explicitly

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
2. Code owners run a dispatch mode workflow to automatically generate version and manifests on the release branch
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

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.

Helm chart versioning: The Reloader Helm chart is maintained inthis repository. The Helm chart has its own semantic versioning. Helm charts and code releases are separate artifacts and separately versioned. Manifest making strategy relies on Kustomize. The Reloader Helm chart manages the two artifacts with these two fields:

• appVersion points to released Reloader application image version listed on thereleases page
• version sets the Reloader Helm chart version

Helm chart will be released to the chart registry whenever files indeployments/kubernetes/chart/reloader/** change on the main branch.

Helm Chart will be released by the maintainers, on labelling a PR withrelease/helm-chart and pre-maturely updating theversion field inChart.yaml file.

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 projectsor contact us in case of professional services and queries onhello@stakater.com

• ConfigmapController; We documentedhere why we re-created Reloader