leaderelection

Documentation

Overview

LeaderElection provides an interface for controllers implementing using controller injection: https://github.com/knative/pkg/blob/main/injection/README.md

Leaderelection uses the context-stuffing mechanism to provide config-driven management of multiple election strategies (currently, using Kubernetes etcd-based election primitives or StatefulSet indexes and counts).

For more details, see the original design document: https://docs.google.com/document/d/e/2PACX-1vTh40N-Kk6EPNzYpITiLg8YJk0qZyZv7KgMpcQS72T9Lv_F2PQeGybx4TtH0E1N1aUgLQer7b8u3lDc/pub

Index

• Variables
• func ConfigMapName() string
• func HasLeaderElection(ctx context.Context) bool
• func NewStatefulSetBucketAndSet(buckets int) (reconciler.Bucket, *hash.BucketSet, error)
• func UniqueID() (string, error)
• func WithConfig(ctx context.Context, cfg *Config) context.Context
• func WithDynamicLeaderElectorBuilder(ctx context.Context, kc kubernetes.Interface, cc ComponentConfig) context.Context
• func WithStandardLeaderElectorBuilder(ctx context.Context, kc kubernetes.Interface, cc ComponentConfig) context.Context
• func WithStatefulSetElectorBuilder(ctx context.Context, cc ComponentConfig, bkt reconciler.Bucket) context.Context
• type ComponentConfig
• type Config
  • func GetConfig(ctx context.Context) *Config
  • func NewConfigFromConfigMap(configMap *corev1.ConfigMap) (*Config, error)
  • func NewConfigFromMap(data map[string]string) (*Config, error)
  • func (c *Config) GetComponentConfig(name string) ComponentConfig
• type Elector
  • func BuildElector(ctx context.Context, la reconciler.LeaderAware, queueName string, ...) (Elector, error)
• type ElectorWithInitialBuckets

Variables

var MaxBuckets uint32 = 10

MaxBuckets is the maximum number of buckets to allow users to define. This is a variable so that it may be customized in the binary entrypoint.

Functions

func ConfigMapName

func ConfigMapName() string

ConfigMapName returns the name of the configmap to read for leader election settings.

func HasLeaderElection

func HasLeaderElection(ctx context.Context) bool

HasLeaderElection returns whether there is leader election configuration associated with the context

func NewStatefulSetBucketAndSet

func NewStatefulSetBucketAndSet(buckets int) (reconciler.Bucket, *hash.BucketSet, error)

NewStatefulSetBucketAndSet creates a BucketSet for StatefulSet controller with the given bucket size and the information from environment variables. Then uses the created BucketSet to create a Bucket for this StatefulSet Pod.

func UniqueID

func UniqueID() (string, error)

UniqueID returns a unique ID for use with a leader elector that prevents from pods running on the same host from colliding with one another.

func WithConfig

func WithConfig(ctx context.Context, cfg *Config) context.Context

WithConfig associates a leader election configuration with the context.

func WithDynamicLeaderElectorBuilder

func WithDynamicLeaderElectorBuilder(ctx context.Context, kc kubernetes.Interface, cc ComponentConfig) context.Context

WithDynamicLeaderElectorBuilder sets up the statefulset elector based on environment, falling back on the standard elector.

func WithStandardLeaderElectorBuilder

func WithStandardLeaderElectorBuilder(ctx context.Context, kc kubernetes.Interface, cc ComponentConfig) context.Context

WithStandardLeaderElectorBuilder infuses a context with the ability to build LeaderElectors with the provided component configuration acquiring resource locks via the provided kubernetes client.

func WithStatefulSetElectorBuilder

func WithStatefulSetElectorBuilder(ctx context.Context, cc ComponentConfig, bkt reconciler.Bucket) context.Context

WithStatefulSetElectorBuilder infuses a context with the ability to build Electors which are assigned leadership based on the StatefulSet ordinal from the provided component configuration.

Types

type ComponentConfig

type ComponentConfig struct {
	Component     string
	Buckets       uint32
	LeaseDuration time.Duration
	RenewDeadline time.Duration
	RetryPeriod   time.Duration
	// LeaseName is a function to customize the lease name given the index i.
	// If not present, a name in format {Component}.{queue-name}.{i}-of-{Buckets}
	// will be use.
	// Autoscaler need to know the Lease names to filter out Leases which are not
	// used for Autoscaler. Instead of exposing the names from leadelection package,
	// we let Autoscaler to pass them in.
	LeaseName func(i uint32) string `json:"-"`
	// Identity is the unique string identifying a resource lock holder across
	// all participants in an election. If not present, a new unique string will
	// be generated to be used as identity for each BuildElector call.
	// Autoscaler uses the pod IP as identity.
	Identity string

	// LeaseNamesPrefixMapping maps lease prefixes
	// from <component>.<package>.<reconciler_type_name> to the
	// associated value when using standardBuilder.
	LeaseNamesPrefixMapping map[string]string
}

ComponentConfig represents the leader election config for a single component.

type Config

type Config struct {
	Buckets                 uint32
	LeaseDuration           time.Duration
	RenewDeadline           time.Duration
	RetryPeriod             time.Duration
	LeaseNamesPrefixMapping map[string]string
}

Config represents the leader election config for a set of components contained within a single namespace. Typically these will correspond to a single source repository, viz: serving or eventing.

func GetConfig

func GetConfig(ctx context.Context) *Config

GetConfig gets the leader election config from the provided context.

func NewConfigFromConfigMap

func NewConfigFromConfigMap(configMap *corev1.ConfigMap) (*Config, error)

NewConfigFromConfigMap returns a new Config from the given ConfigMap.

func NewConfigFromMap

func NewConfigFromMap(data map[string]string) (*Config, error)

NewConfigFromMap returns a Config for the given map, or an error.

func (*Config) GetComponentConfig

func (c *Config) GetComponentConfig(name string) ComponentConfig

type Elector

type Elector interface {
	Run(context.Context)
}

Elector is the interface for running a leader elector.

func BuildElector

func BuildElector(ctx context.Context, la reconciler.LeaderAware, queueName string, enq func(reconciler.Bucket, types.NamespacedName)) (Elector, error)

BuildElector builds a leaderelection.LeaderElector for the named LeaderAware reconciler using a builder added to the context via WithStandardLeaderElectorBuilder.

type ElectorWithInitialBuckets

type ElectorWithInitialBuckets interface {
	InitialBuckets() []reconciler.Bucket
}

ElectorWithInitialBuckets is an optional interface for electors to supply an initial set of buckets