Categorygithub.com/grafana/ckit
modulepackage
0.0.0-20240807005918-f250363a52ad
Repository: https://github.com/grafana/ckit.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
22
Dependents
2
Files
862 SLOC

# README

ckit

Go Reference

ckit (clustering toolkit) is a lightweight package for creating clusters that use consistent hashing for workload distribution.

ckit works by gossiping member state over HTTP/2, and locally generating hashing algorithms based on the state of nodes in the cluster. Because gossip is used, the hashing algorithms are eventually consistent as cluster state takes time to converge.

NOTE: ckit is still in development; breaking changes to the API may happen.

Features

  • Low-overhead: on a 151 node cluster, ckit uses ~20MB of memory and ~50Bps of network traffic per node.

  • HTTP/2 transport: nodes communicate over plain HTTP/2 without needing to open up extra ports.

Packages

ckit has two main packages:

  • The top-level package handles establishing a cluster.
  • The shard package handles creating consistent hashing algorithms based on cluster state.

There are also some utility packages:

  • The advertise package contains utilities for a node to determine what IP address to advertise to its peers.
  • The memconn package contains utilities for a node to create an in-memory connection to itself without using the network.

Comparison to grafana/dskit

grafana/dskit is a mature library with utilities for building distributed systems in general. Its clustering mechanism works by gossiping a 32-bit hash ring over the network. In comparison, ckit locally computes 64-bit hash rings.

dskit was built for Grafana Labs' time-series databases, while ckit was initially built for Grafana Agent, with the intent of building something with less operational overhead.

Compared to ckit, the dskit library:

  • Is more mature, and is used at scale with Grafana Mimir, Grafana Loki, and Grafana Tempo.

  • Gossips hash rings over the network, leading to more complexity and more network overhead.

  • Uses a 32-bit hash ring for distributing work; ckit has multiple 64-bit hashing algorithms to choose from.

  • Requires a separate listener for gossip traffic; ckit allows reusing your existing HTTP/2-capable server.

# Packages

Package advertise provide utilities to find addresses to advertise to cluster peers.
Package memconn provides an in-memory network connections.
Package peer describes a ckit peer.
Package shard implements a set of consistent hashing algorithms to determine ownership of a key within a cluster.

# Functions

NewNode creates an unstarted Node to participulate in a cluster.
ParticipantObserver wraps an observer and filters out events where the list of peers in the Participants state haven't changed.

# Variables

ErrStopped is returned by invoking methods against Node when it is stopped.

# Structs

Config configures a Node within the cluster.
A Node is a participant in a cluster.
StateTransitionError is returned when a node requests an invalid state transition.

# Interfaces

An Observer watches a Node, waiting for its peers to change.

# Type aliases

FuncObserver implements Observer.