k8s-elector is a minimal Kubernetes-native sidecar elector service, allowing you to perform simple leader election within your Kubernetes deployment.

Internally, it uses "k8s.io/client-go/tools/leaderelection" to run the election.

The k8s-elector is intended to be run as a sidecar to other services to provide them leader election capabilities, but it can run on its own as well. For an example, you can run just the elector containers with

$ kubectl run k8s-elector --image=vaporio/k8s-elector --replicas=3 -- -election=example

Note By default, k8s-elector tries to use a Kubernetes LeaseLock. If running a version of Kubernetes which does not support this, you can change the lock type with the -lock-type flag. (valid values: leases, endpoints, configmaps)

This will run 3 instances of the k8s-elector. You can observe their logs to verify a leader is chosen among them.

Looking through the logs for leadership is not tenable for a deployment to identify leadership. k8s-elector exposes a basic HTTP API to provide leadership status information. You can enable and conifgure it with the -http flag.

$ kubectl run k8s-elector --image=vaporio/k8s-elector --replicas=3 -- -election=example -lock-type=configmaps -http=0.0.0.0:5002

You can look through the logs to see a leader was elected and you can verify from within the cluster that each pod reports its leadership status correctly.

/ # curl 10.1.0.180:5002/
{"is_leader":false,"leader":"k8s-elector-74c54b485f-hgf9z","node":"k8s-elector-74c54b485f-564ht","timestamp":"2019-05-02T18:28:51Z"}
/ # curl 10.1.0.181:5002/
{"is_leader":false,"leader":"k8s-elector-74c54b485f-hgf9z","node":"k8s-elector-74c54b485f-qztgk","timestamp":"2019-05-02T18:29:21Z"}
/ # curl 10.1.0.179:5002/
{"is_leader":true,"leader":"k8s-elector-74c54b485f-hgf9z","node":"k8s-elector-74c54b485f-hgf9z","timestamp":"2019-05-02T18:29:26Z"}

As the above run command specified the lock type as "configmaps", you should also expect to see a ConfigMap with the same name as the election.

$ kubectl get cm
NAME      DATA      AGE
example   0         21m

For a full list of configuration options, you can run the elector with the -h flags. These will include both the flags for the elector itself as well as flags for configuring logging.

Usage of ./elector:
  -election string
    	The name of the election. This is required.
  -http string
    	The HTTP address (host:port) which leader state will be reported on.
  -id string
    	The ID of the election participant. If not set, the hostname, as reported by the kernel, is used.
  -kubeconfig string
    	The kubeconfig file to use. If not set, in-cluster config will be used.
  -lock-type string
    	The type of Kubernetes object to use for the lock (leases, endpoints, configmaps) (default "leases")
  -namespace string
    	The Kubernetes namespace to run the election in. If not set, elections will run in the default namespace. (default "default")
  -ttl duration
    	The TTL for the election. (default 10s)

When enabled, the exposed HTTP API consists of a single endpoint at the URL root.

Method: GET

{
  "is_leader": false,
  "leader": "k8s-elector-74c54b485f-hgf9z",
  "node": "k8s-elector-74c54b485f-564ht",
  "timestamp": "2019-05-02T18:28:51Z"
}