kubeprobes

README

kubeprobes

Simple and effective package for implementing Kubernetes liveness and readiness probes' handler.

Installation

go get -u pkg.icikowski.pl/kubeprobes

Usage

The package provides kubeprobes.New function which returns a probes handler of type kubeprobes.Kubeprobes, which is compliant with http.Handler interface.

The handler serves two endpoints, which are used to implement liveness and readiness probes by returning either 200 (healthy) or 503 (unhealthy) status and JSON response with probes results:

• /live - endpoint for liveness probe;
• /ready - endpoint for readiness probe.

Default paths can be overriden with options described below. Accessing any other endpoint will return 404 status. By default, response body only contains a list of failed probes, but this behavior can be changed with provided option or by adding ?v query parameter.

The kubeprobes.New function accepts following options as arguments:

• kubeprobes.WithLivenessProbes(...) - adds particular probes to the list of liveness probes;
• kubeprobes.WithLivenessPath("/some/liveness/path") - sets liveness probe path to given path (default is /live);
• kubeprobes.WithReadinessProbes(...) - adds particular probes to the list of readiness probes;
• kubeprobes.WithReadinessPath("/some/readiness/path") - sets readiness probe path to given path (default is /ready);
• kubeprobes.WithVerboseOutput() - enables verbose output by default (returns both failed and passed probes).

Probes

In order to determine the state of particular element of application, probes need to be implemented either by creating probes from functions or by using simple and thread-safe manual probes.

Standard probes

Probes (instances of Probe interface) are wrappers for functions that performs user defined logic with given interval of updates in order to determine whether the probe should be marked as healthy or not. Those functions should take no arguments and return error (if no error is returned, the probe is considered to be healthy; if error is returned, the probe is considered to be unhealthy). If given interval is less or equal zero, then function is only checked on probe creation and remains in determined state forever.

someProbe := kubeprobes.NewProbe("live", func() error {
    // Some logic here
    if time.Now().Weekday() == time.Wednesday {
        // Fail only on wednesday!
        return errors.New("It's wednesday, my dudes!")
    }
    return nil
}, 1 * time.Hour)

someOtherProbe := kubeprobes.NewProbe("ready", func() error {
    // Always healthy
    return nil
}, 0) // This probe is checked once

// Use functions in probes handler
kp, _ := kubeprobes.New(
    kubeprobes.WithLivenessProbes(someOtherProbe),
    kubeprobes.WithReadinessProbes(someProbe),
)

Manual probes

Manual probes (instances of ManualProbe interface) are objects that can be marked either as healthy or unhealthy and implement Probe for easy integration. Those objects utilize sync.RMutex mechanism to ensure thread-safety.

Those probes can be changed by user with provided methods:

• Pass() marks probe as healthy;
• Fail() marks probe as unhealthy with generic cause;
• FailWithCause(someError) marks probe as unhealthy with given error as cause.

// Unhealthy by default
someProbe := kubeprobes.NewManualProbe("live")
someOtherProbe := kubeprobes.NewManualProbe("ready")

// Use it in probes handler
kp, _ := kubeprobes.New(
    kubeprobes.WithLivenessProbes(someProbe),
    kubeprobes.WithReadinessProbes(someOtherProbe),
)

// Can be later marked according to needs
someProbe.Pass()
someOtherProbe.FailWithCause(errors.New("I'm not doing anything!"))

Direct handler access

It is possible to fetch http.Handlers for liveness & readiness probes from kubeprobes.Kubeprobes instance as follows:

kp, _ := kubeprobes.New(
    // ...
)

livenessHandler := kp.LivenessHandler()
readinessHandler := kp.ReadinessHandler()

Those handler can be used for manually mounting them on other servers/routers/muxes (eg. go-chi/chi, gorilla/mux, http's ServeMux etc.).

Example usage

// Create probe functions
appProbe := func() error {
    // Some logic for checking app status
    return nil
}

// Create manual probes
live := kubeprobes.NewManualProbe("liveness") 
ready := kubeprobes.NewManualProbe("readiness")

// Prepare handler
kp, err := kubeprobes.New(
    kubeprobes.WithLivenessProbes(live),
    kubeprobes.WithReadinessProbes(ready, appProbe),
    kubeprobes.WithLivenessPath("/livez"),
    kubeprobes.WithReadinessPath("/readyz"),
    kubeprobes.WithVerboseOutput(),
)
if err != nil {
    // Kubeprobes object is validated for invalid or conflicting paths! ;)
    panic(err)
}

// Start the probes server
probes := &http.Server{
    Addr:    ":8080",
    Handler: kp,
}
go probes.ListenAndServe()

// Mark probes as healthy
live.Pass()
ready.Pass()

Documentation

Index

• type Kubeprobes
  • func New(options ...Option) (Kubeprobes, error)
• type ManualProbe
  • func NewManualProbe(name string) (ManualProbe, error)
• type Option
  • func WithLivenessPath(path string) Option
  • func WithLivenessProbes(probes ...Probe) Option
  • func WithReadinessPath(path string) Option
  • func WithReadinessProbes(probes ...Probe) Option
  • func WithVerboseOutput() Option
• type Probe
  • func NewProbe(name string, fn func() error, updateInterval time.Duration) (Probe, error)

Types

type Kubeprobes

type Kubeprobes interface {
	http.Handler

	// LivenessHandler returns [http.Handler] for liveness probes.
	LivenessHandler() http.Handler
	// ReadinessHandler returns [http.Handler] for readiness probes.
	ReadinessHandler() http.Handler
}

Kubeprobes represents liveness & readiness probes handler.

func New

func New(options ...Option) (Kubeprobes, error)

New returns a new instance of a Kubernetes probes with given options.

type ManualProbe

type ManualProbe interface {
	Probe

	// Pass marks the probe as healthy.
	Pass()
	// Fail marks the probe as unhealthy.
	Fail()
	// FailWitCause marks the probe as unhealthy with given cause.
	FailWithCause(err error)
}

ManualProbe represents the simple probe that can be either marked as "up" (healthy) or "down" (unhealthy).

func NewManualProbe

func NewManualProbe(name string) (ManualProbe, error)

NewManualProbe returns a new instance of a manual probe which can be either marked as healthy or unhealthy. The probe is initially marked as unhealthy.

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option represents a Kubeprobes constructor option.

func WithLivenessPath

func WithLivenessPath(path string) Option

WithLivenessPath sets custom path for liveness probe (default is "/live").

func WithLivenessProbes

func WithLivenessProbes(probes ...Probe) Option

WithLivenessProbes adds given probe functions to the set of liveness probes.

func WithReadinessPath

func WithReadinessPath(path string) Option

WithReadinessPath sets custom path for readiness probe (default is "/ready").

func WithReadinessProbes

func WithReadinessProbes(probes ...Probe) Option

WithReadinessProbes adds given probe functions to the set of readiness probes.

func WithVerboseOutput

func WithVerboseOutput() Option

WithVerboseOutput enables verbose output for every request.

type Probe

type Probe interface {
	// contains filtered or unexported methods
}

Probe is a wrapper for a function that determines whether the given metric may be marked as correctly functioning. It not, the error should be returned.

func NewProbe

func NewProbe(
	name string,
	fn func() error,
	updateInterval time.Duration,
) (Probe, error)

NewProbe returns new instance of Probe.

If update interval is less or equal zero then probe is updated only on its creation and remains in the same state forever.