8 releases
0.2.0 | Jul 24, 2024 |
---|---|
0.1.6 | Jul 24, 2024 |
#192 in Asynchronous
91 downloads per month
110KB
1.5K
SLoC
kube-lease-manager
Ergonomic and reliable leader election using Kubernetes Lease API.
kube-lease-manager
is a high-level helper to facilitate leader election using
Lease Kubernetes resource.
It ensures that only a single instance of the lease managers holds the lock at any moment of time.
Some of the typical use cases:
- automatic coordination of leader election between several instances (Pods) of Kubernetes controllers;
- ensure only a single instance of concurrent jobs is running right now;
- exclusive acquiring of shared resource.
Features
LeaseManager
is a central part of the crate. This is a convenient wrapper around a KubernetesLease
resource to manage all aspects of leader election process.- Provides two different high-level approaches to lock and release lease: fully automated or partially manual lock control.
- Uses Server-Side-Apply approach to update lease state that facilitates conflict detection and resolution and makes impossible concurrent locking.
- Tolerate configurable time skew between nodes of the Kubernetes cluster.
- Behavioral parameters of the lease manager are easily and flexibly configurable.
- Uses well-known and highly appreciated kube and Tokio crates to access Kubernetes API and coordinate asynchronous tasks execution.
- You don't need to use low-level Kubernetes API.
- Uses Tokio tracing carte to provide event logs.
Please visit crate's documentation to get details and more examples.
As mentioned above, kube-lease-manager
provides two possible ways to manage lease lock:
- Fully automated: you create
LeaseManager
instance and run itswatch()
method. It returns Tokio watch channel to watch on state changes Besides that it runs an unattended background task which permanently tries to lock lease if it's free and publish changed state to the channel. The task finishes if the channel is closed. - Partially manual: you create
LeaseManager
instance and use itschanged()
andrelease()
methods to control lock.changed()
tries to lock lease as soon as it becomes free and returns actual lock state when it's changed. Your responsibilities are:- to keep
changed()
running (it's aFuture
) to ensure lock is refreshing while it's in use; - to call
release()
when you don't need the lock and want to make it free for others.
- to keep
First way ensures that lease is locked (has a holder) at any moment of time. Second makes possible to acquire and release lock when you need it.
Example
The simplest example using first locking approach:
use kube::Client;
use kube_lease_manager::{LeaseManagerBuilder, Result};
use std::time::Duration;
#[tokio::main]
async fn main() {
// Use default Kube client
let client = Client::try_default().await?;
// Create the simplest LeaseManager with reasonable defaults using convenient builder.
// It uses Lease resource called `test-watch-lease`.
let manager = LeaseManagerBuilder::new(client, "test-watch-lease")
.build()
.await?;
let (mut channel, task) = manager.watch().await;
// Watch on the channel for lock state changes
tokio::select! {
_ = channel.changed() => {
let lock_state = *channel.borrow_and_update();
if lock_state {
// Do something useful as a leader
println!("Got a luck!");
}
}
_ = tokio::time::sleep(Duration::from_secs(10)) => {
println!("Unable get lock during 10s");
}
}
// Explicitly close the control channel
drop(channel);
// Wait for the finish of the manager and get it back
let _manager = tokio::join!(task).0.unwrap()?;
Ok(())
}
Please visit crate's documentation to get more examples and usage details.
TODO
- Provide some real and useful examples.
Credits
The author was inspired on this piece of work by two other crates that provide similar functionality: kubert and kube-leader-election. Both of them are great, thanks to the authors. But both have something missing for one of my projects. So it was a reason to create this one.
License
This project is licensed under the MIT license.
Dependencies
~66MB
~1M SLoC