Skip to content
Kubernetes configuration tracking controller
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
cmd/manager fix typo (#23) Nov 14, 2018
config Update command in Manager StatefulSet Jan 4, 2019
pkg Remove unnecessary cast Jan 26, 2019
test/utils Simplify handling of optional keys Jan 23, 2019
.gitignore Initial Commit Oct 19, 2018
Gopkg.toml Move test suite to Ginkgo Oct 22, 2018
LICENSE Initial Commit Oct 19, 2018
PROJECT Typo in README Jan 30, 2019
wave-logo.svg Add logo to ReadMe Nov 20, 2018
wercker.yml Pin alpine base image Nov 22, 2018

Wave Logo


Wave watches Deployments within a Kubernetes cluster and ensures that each Deployment's Pods always have up to date configuration.

By monitoring ConfigMaps and Secrets mounted by a Deployment, Wave can trigger a Rolling Update of the Deployment when the mounted configuration is changed.

Table of Contents


Not all software is built equal. Some applications can automatically reload their configuration and continue running with the updated configuration, while others will just continue running the old configuration until their process dies. Wave is here to help those applications that do not support dynamic configuration reloading.

When deploying applications to Kubernetes, it is common practice to deploy configuration using ConfigMaps and Secrets, mounted into the Pod either as environment variables or in files.

When this configuration is updated, if the software consuming the configuration is not able to dynamically reload, it will continue running the old configuration until the Pod is killed, this leads to inconsistency between the supposed desired state of the application and the running state of the application.

Wave monitors Deployments and their underlying configuration and will trigger the Kubernetes Deployment controller to update the application and bring up new Pods whenever the underlying configuration is changed.

This means that, with Wave, whenever a ConfigMap or Secret is updated, all Deployments mounting the configuration will bring up new Pods on the cluster and remove the old Pods with the out-of-date configuration.

Wave gives application developers confidence that the deployed configuration, matches the live configuration. It allows developers to discover misconfiguration as it is deployed, rather than when the Pods happen to be re-cycled.


Deploying to Kubernetes

Wave is a Kubebuilder based project, as such we have auto-generated Kustomize configuration as an example of how to install the controller in the config folder.

A public docker image is available on Quay.


If you are using RBAC within your cluster, you must grant the service account used by your Wave instance permission to read all Secrets, ConfigMaps and Deployments and the ability to update Deployments within each namespace in the cluster.

Example ClusterRole and ClusterRoleBindings are available in the config/rbac folder.


The following section details the various configuration options that Wave provides at the controller level.

Leader Election

Wave can be run in an active-standby HA configuration using Kubernetes leader election. When leader election is enabled, each Pod will attempt to become leader and, whichever is successful, will become the active or master controller. The master will perform all of the reconciliation of Resources.

The standby Pods will sit and wait until the leader goes away and then one standby will be promoted to master.

To enable leader election, set the following flags:


Sync period

The controller uses Kubernetes informers to cache resources and reduce load on the Kubernetes API server. Every informer has a sync period, after which it will refresh all resources within its cache. At this point, every item in the cache is queued for reconciliation by the controller.

Therefore, by setting the following flag;

--sync-period=5m // Default value of 5m (5 minutes)

You can ensure that every resource will be reconciled at least every 5 minutes.

Quick Start

If you haven't yet got Wave running on your cluster, see Installation for details on how to get it running.

Wave watches all Deployments within a cluster but only processes those that have the annotation "true" which allows individual service owners to opt-in to the Wave controller.

Therefore, to enable Wave for your Deployment, add the annotation to your Deployment as shown below:

apiVersion: apps/v1
kind: Deployment
  annotations: "true"

Once enabled, Wave will set the initial configuration hash as an annotation on the Deployment's PodTemplate. You will be able to see this when reading your Deployment:

$ kubectl get deployment foo
apiVersion: apps/v1
kind: Deployment
  name: foo
  namespace: default
  annotations: "true"
      annotations: "<SHA256_HASH>"

From now on, when a mounted ConfigMap or Secret is updated, Wave will update this config-hash annotation and cause a Rolling Update to occur.

Project Concepts

This section outlines some of the underlying concepts that enable this controller to work the way it does.

Enabling Wave for a Deployment

Wave acts as an opt-in controller on a per Deployment basis. Before processing any Deployment, Wave checks for the presence of a "Required annotation". If the annotation is not present, Wave will ignore the Deployment.

Therefore, to enable Wave for your Deployment, add the annotation to your Deployment as shown below:

apiVersion: apps/v1
kind: Deployment
  annotations: "true"

Wave will now start processing this Deployment.

Triggering Updates

Wave monitors the data stored in ConfigMaps and Secrets referenced within a Deployment. By calculating a SHA256 hash of the data in a reproducible manner, Wave can determine when the data with the ConfigMaps and Secrets has changed.

Wave stores the calculated hash as an annotation on the PodTemplate within the Deployment's specification and will update the Deployment whenever the hash is changed.

Modifying the PodTemplate in this way causes the Kubernetes Deployment controller to start a Rolling Update of the Deployment's Pods without changing any of the configuration of the containers or other controllers operation on the Pods and Deployment.


Wave adds an OwnerReference to all ConfigMaps and Secrets that are referenced by a Deployment. This allows Wave to trigger a reconciliation whenever the ConfigMaps or Secrets are modified.

Normally, when an owner is deleted, the Kubernetes Garbage Collector deletes all child resources. This is not desirable and so Wave prevents this from happening.

Wave managed Deployments will have a Finalizer added to them. This allows Wave to perform advanced clean-up operation when a Deployment is deleted.

When Wave encounters a Deployment marked for deletion that has the Wave Finalizer, it checks for all ConfigMaps and Secrets with an OwnerReference pointing to the Deployment and removes the OwnerReference. Thus preventing the ConfigMaps and Secrets from being delted by the Garbage Collector.

Read the docs for more about Kubernetes Garbage Collection.


  • Found a bug? Please open an issue.
  • Have a feature request. Please open an issue.
  • If you want to contribute, please submit a pull request


Please see our Contributing guidelines.


This project is licensed under Apache 2.0 and a copy of the license is available here.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.