leader

Documentation

Overview

Package leader implements Leader For Life, a simple alternative to lease-based leader election.

Both the Leader For Life and lease-based approaches to leader election are built on the concept that each candidate will attempt to create a resource with the same GVK, namespace, and name. Whichever candidate succeeds becomes the leader. The rest receive "already exists" errors and wait for a new opportunity.

Leases provide a way to indirectly observe whether the leader still exists. The leader must periodically renew its lease, usually by updating a timestamp in its lock record. If it fails to do so, it is presumed dead, and a new election takes place. If the leader is in fact still alive but unreachable, it is expected to gracefully step down. A variety of factors can cause a leader to fail at updating its lease, but continue acting as the leader before succeeding at stepping down.

In the "leader for life" approach, a specific Pod is the leader. Once established (by creating a lock record), the Pod is the leader until it is destroyed. There is no possibility for multiple pods to think they are the leader at the same time. The leader does not need to renew a lease, consider stepping down, or do anything related to election activity once it becomes the leader.

The lock record in this case is a ConfigMap whose OwnerReference is set to the Pod that is the leader. When the leader is destroyed, the ConfigMap gets garbage-collected, enabling a different candidate Pod to become the leader.

Leader for Life requires that all candidate Pods be in the same Namespace. It uses the downwards API to determine the pod name, as hostname is not reliable. You should run it configured with:

env:

• name: POD_NAME valueFrom: fieldRef: fieldPath: metadata.name

Index

• func Become(ctx context.Context, lockName string) error

Functions

func Become

func Become(ctx context.Context, lockName string) error

Become ensures that the current pod is the leader within its namespace. If run outside a cluster, it will skip leader election and return nil. It continuously tries to create a ConfigMap with the provided name and the current pod set as the owner reference. Only one can exist at a time with the same name, so the pod that successfully creates the ConfigMap is the leader. Upon termination of that pod, the garbage collector will delete the ConfigMap, enabling a different pod to become the leader.