k8slock

README

k8slock

k8slock is a Go module that makes it easy to do distributed locking using the Lease resource from the Kubernetes coordination API.

If you want to use Kubernetes to create a simple distributed lock, this module is for you.

This module implements the sync.Locker interface using the Lock() and Unlock() functions.

Basic Usage

package main

import "github.com/LougaoCloud/k8slock"

func main() {
    locker, err := k8slock.NewLocker("example-lock")
    if err != nil {
        panic(err)
    }

    locker.Lock()
    // do some work
    locker.Unlock()
}

Basic Usage – Context

package main

import (
    "context"
    "github.com/LougaoCloud/k8slock"
)

func main() {
    locker, err := k8slock.NewLocker("example-lock", k8slock.Context(context.Background()))
    if err != nil {
        panic(err)
    }

    locker.Lock()
    // do some work
    locker.Unlock()
}

Locker Options

The locker can be configured using the following functional options:

Option	Details
TTL(duration)	The duration until the lock expires and can be forcibly claimed. By default the lock can be held infinitely.
RetryWaitDuration(duration)	The duration to wait before retrying after failing to acquired the lock. Default: 1 second.
InClusterConfig()	Get the kubernetes client config from inside a pod. Defaults to a clientset using the local kubeconfig.
Clientset(kubernetes.Interface)	Configure a custom Kubernetes Clientset. Defaults to a clientset using the local kubeconfig.
Namespace(string)	The kubernetes namespace to store the Lease resource. Defaults to "default".
ClientID(string)	A unique ID for the client that is trying to obtain the lock. Defaults to a random UUID.
Context(context.Context)	The context to use for the lock. Defaults to context.WithTimeout(context.Background(), 10*time.Second).

e.g:

locker, err := k8slock.NewLocker("example-lock", k8slock.Namespace("locks"), k8slock.ClientID("client-0"))

Documentation

Index

• func ClientID(id string) lockerOption
• func Context(ctx context.Context) lockerOption
• func InClusterClient() lockerOption
• func K8sClient(c client.Client) lockerOption
• func Namespace(ns string) lockerOption
• func OwnerRef(ownerRef *metav1.OwnerReference) lockerOption
• func RetryWaitDuration(d time.Duration) lockerOption
• func TTL(ttl time.Duration) lockerOption
• type Locker
  • func NewLocker(name string, options ...lockerOption) (*Locker, error)
  • func (l *Locker) Lock()
  • func (l *Locker) Unlock()

Functions

func ClientID

func ClientID(id string) lockerOption

ClientID is a unique ID for the client acquiring the lock

func Context

func Context(ctx context.Context) lockerOption

func InClusterClient

func InClusterClient() lockerOption

InClusterClient configures the Kubernetes client assuming it is running inside a pod

func K8sClient

func K8sClient(c client.Client) lockerOption

K8sClient configures the Kubernetes client.

func Namespace

func Namespace(ns string) lockerOption

Namespace is the namespace used to store the Lease

func OwnerRef

func OwnerRef(ownerRef *metav1.OwnerReference) lockerOption

OwnerRef is the OwnerReference to set on the Lease. This is useful if you want to delete the Lease when the owner is deleted.

func RetryWaitDuration

func RetryWaitDuration(d time.Duration) lockerOption

RetryWaitDuration is the duration the Lock function will wait before retrying after failing to acquire the lock, defaults to 100 milliseconds

func TTL

func TTL(ttl time.Duration) lockerOption

TTL is the duration a lock can exist before it can be forcibly acquired by another client, defaults to 15 seconds

Types

type Locker

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

Locker implements the Locker interface using the kubernetes Lease resource

func NewLocker

func NewLocker(name string, options ...lockerOption) (*Locker, error)

NewLocker creates a Locker

func (*Locker) Lock

func (l *Locker) Lock()

Lock blocks until the lock is acquired or the context is cancelled

func (*Locker) Unlock

func (l *Locker) Unlock()