shard

Documentation

Overview

Package shard implements static, hash-based ownership so alert evaluation and delivery can be distributed across N active replicas (A2 in the design doc).

Model: every replica watches the whole cluster (informer caches are cheap relative to delivery), but a replica only *acts* on an object it owns, where ownership is a pure function of a stable object key:

owns(key) == (fnv32a(key) mod total == index)

Because ownership is deterministic and depends only on the key, at any instant exactly one replica owns a given object - so no two replicas page for it. This is the same sharding model Prometheus/Thanos use. Rebalancing happens by changing total/index (a StatefulSet rollout), which is simpler and safer than a dynamic coordinator; the trade-off is that scaling requires a rollout.

Sharding is disabled (own everything) unless total > 1, so a default single replica behaves exactly as before.

Index

• Constants
• type Sharder
  • func FromEnv() (*Sharder, error)
  • func New(index, total int) (s *Sharder, ok bool)
  • func (s *Sharder) Enabled() bool
  • func (s *Sharder) Index() int
  • func (s *Sharder) Owns(key string) bool
  • func (s *Sharder) Total() int

Constants

const (
	EnvTotal = "ALERTKUBE_SHARD_TOTAL"
	EnvIndex = "ALERTKUBE_SHARD_INDEX"
)

Env var names for the static shard assignment. They live beside the ownership model they configure because the shard identity is consumed at three points that are wired at different moments in startup - the leader Lease name, the persisted-state ConfigMap name, and the emit-path ownership gate - and a single parse is what keeps those three from disagreeing. Two of them (Lease, ConfigMap) are resolved before the controller body runs, which is why this cannot stay buried in the controller.

Types

type Sharder

type Sharder struct {
	// contains filtered or unexported fields
}

Sharder decides whether the local replica owns a key. The zero value and nil both mean "own everything" (sharding disabled).

func FromEnv

func FromEnv() (*Sharder, error)

FromEnv builds the Sharder from ALERTKUBE_SHARD_TOTAL / ALERTKUBE_SHARD_INDEX. The defaults (total 1) disable sharding, so an unset environment yields a replica that owns everything - the unchanged single-replica behavior.

An out-of-range index returns an error rather than a silently-degraded Sharder: a replica that owns nothing looks perfectly healthy (informers sync, /readyz is green, no errors are logged) while paging for its whole share of the cluster stops. That must fail at startup, not in production.

func New

func New(index, total int) (s *Sharder, ok bool)

New returns a Sharder for replica index of total. total <= 1 disables sharding (owns everything) and the index is ignored. ok is false only when sharding is requested (total > 1) but index is out of range, so the caller can fail fast on a misconfigured shard set.

func (*Sharder) Enabled

func (s *Sharder) Enabled() bool

Enabled reports whether sharding is active (total > 1).

func (*Sharder) Index

func (s *Sharder) Index() int

Index and Total expose the configuration for logging/metrics.

func (*Sharder) Owns

func (s *Sharder) Owns(key string) bool

Owns reports whether the local replica is responsible for key. When sharding is disabled it always returns true, so the ownership gate is a no-op on a single replica.

func (*Sharder) Total

func (s *Sharder) Total() int