RELOADER

Problem

We would like to watch if some change happens in ConfigMap and/or Secret; then perform a rolling upgrade on relevant DeploymentConfig, Deployment, Daemonset and Statefulset

Solution

Reloader can watch changes in ConfigMap and Secret and do rolling upgrades on Pods with their associated DeploymentConfigs, Deployments, Daemonsets and Statefulsets.

Compatibility

Reloader is compatible with kubernetes >= 1.9

How to use Reloader

For a Deployment called foo have a ConfigMap called foo-configmap or Secret called foo-secret or both. Then add your annotation (by default reloader.stakater.com/auto) to main metadata of your Deployment

kind: Deployment
metadata:
  annotations:
    reloader.stakater.com/auto: "true"
spec:
  template: metadata:

This will discover deployments/daemonsets/statefulset automatically where foo-configmap or foo-secret is being used either via environment variable or from volume mount. And it will perform rolling upgrade on related pods when foo-configmap or foo-secretare updated.

You can restrict this discovery to only ConfigMap or Secret objects that are tagged with a special annotation. To take advantage of that, annotate your deployment/daemonset/statefulset like this:

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

and Reloader will trigger the rolling upgrade upon modification of any ConfigMap or Secret annotated like this:

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

provided the secret/configmap is being used in an environment variable or a volume mount.

Please note that reloader.stakater.com/search and reloader.stakater.com/auto do not work together. If you have the reloader.stakater.com/auto: "true" annotation on your deployment, then it will always restart upon a change in configmaps or secrets it uses, regardless of whether they have the reloader.stakater.com/match: "true" annotation or not.

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 a deployment, daemonset or statefulset. To do this either set the auto annotation to "false" (reloader.stakater.com/auto: "false") or remove it altogether, and use annotations mentioned here or here

Configmap

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

For a Deployment called foo have a ConfigMap called foo-configmap. Then add this annotation to main metadata of your Deployment

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

Use comma separated list to define multiple configmaps.

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

Secret

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

For a Deployment called foo have a Secret called foo-secret. Then add this annotation to main metadata of your Deployment

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

Use comma separated list to define multiple secrets.

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

NOTES

Reloader also supports sealed-secrets. Here are the steps to use sealed-secrets with reloader.
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) in DeploymentConfigs/Deployment/Daemonsets/Statefulsets
secret.reloader.stakater.com/reload or configmap.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 search annotation with the --auto-search-annotation flag and 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 prevent watching certain resources with the --resources-to-ignore flag
you can configure logging in JSON format with the --log-format=json option

Deploying to Kubernetes

You can deploy Reloader by following methods:

Vanilla Manifests

You can apply vanilla manifests by changing RELEASE-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 in default namespace and watches changes secrets and configmaps in all namespaces.

Reloader can be configured to ignore the resources secrets and configmaps by passing the following args (spec.template.spec.containers.args) to its container :

Args	Description
--resources-to-ignore=configMaps	To ignore configMaps
--resources-to-ignore=secrets	To ignore secrets

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 to 0.

Vanilla kustomize

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 in default namespace and watches changes secrets and configmaps in all namespaces.

Kustomize

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

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

bases:
  - https://github.com/stakater/Reloader/deployments/kubernetes

namespace: reloader

Helm Charts

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

helm repo add stakater https://stakater.github.io/stakater-charts

helm repo update

helm install stakater/reloader

Note: By default reloader watches in all namespaces. To watch in single namespace, please run following command. It will install reloader in test namespace which will only watch Deployments, Daemonsets and Statefulsets in test namespace.

helm install stakater/reloader --set reloader.watchGlobally=false --namespace test

Reloader can be configured to ignore the resources secrets and configmaps by using the following parameters of values.yaml file:

Parameter	Description	Type
ignoreSecrets	To ignore secrets. Valid value are either `true` or `false`	boolean
ignoreConfigMaps	To ignore configMaps. Valid value are either `true` or `false`	boolean

Note: At one time only one of these resource can be ignored, trying to do it will cause error in helm template compilation.

You can also set the log format of Reloader to json by setting logFormat to json in values.yaml and apply the chart

Help

Documentation

You can find more documentation here

Have a question?

File a GitHub issue, or send us an email.

Talk to us on Slack

Join and talk to us on Slack for discussing Reloader

Contributing

Bug Reports & Feature Requests

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

Developing

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

Fork the repo on GitHub
Clone the project to your own machine
Commit changes to your own branch
Push your work back up to your fork
Submit a Pull request so that we can review your changes

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

Changelog

View our closed Pull Requests.

License

About

Reloader is maintained by Stakater. Like it? Please let us know at hello@stakater.com

See our other projects or contact us in case of professional services and queries on hello@stakater.com

Acknowledgements

ConfigmapController; We documented here why we re-created Reloader

clive-jevons/Reloader