128 lines
4.6 KiB
Markdown
128 lines
4.6 KiB
Markdown
# kubeprobes
|
|
|
|
Simple and effective package for implementing [Kubernetes liveness and readiness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/)' handler.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
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:
|
|
|
|
- `/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. In order to provide maximum performance, no body is ever returned.
|
|
|
|
The `kubeprobes.New` function accepts following options as arguments:
|
|
|
|
- `kubeprobes.WithLivenessProbes(...)` - adds particular [probe functions](#probe-functions) to the list of liveness probes;
|
|
- `kubeprobes.WithLivenessStatefulProbes(...)` - adds particular [`StatefulProbe`s](#stateful-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 [probe functions](#probe-functions) to the list of readiness probes;
|
|
- `kubeprobes.WithReadinessStatefulProbes(...)` - adds particular [`StatefulProbe`s](#stateful-probes) to the list of readiness probes;
|
|
- `kubeprobes.WithReadinessPath("/some/readiness/path")` - sets readiness probe path to given path (default is `/ready`).
|
|
|
|
## Probes
|
|
|
|
In order to determine the state of particular element of application, probes need to be implemented either by creating [status determining function](#probe-functions) or by using simple and thread-safe [stateful probes](#stateful-probes).
|
|
|
|
### Probe functions
|
|
|
|
Probe functions (objects of type `ProbeFunction`) are functions that performs user defined logic 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).
|
|
|
|
```go
|
|
someProbe := func() error {
|
|
// Some logic here
|
|
if somethingIsWrong {
|
|
return errors.New("something is wrong")
|
|
}
|
|
return nil
|
|
}
|
|
|
|
someOtherProbe := func() error {
|
|
// Always healthy
|
|
return nil
|
|
}
|
|
|
|
// Use functions in probes handler
|
|
kp, _ := kubeprobes.New(
|
|
kubeprobes.WithLivenessProbes(someOtherProbe),
|
|
kubeprobes.WithReadinessProbes(someProbe),
|
|
)
|
|
```
|
|
|
|
### Stateful probes
|
|
|
|
Stateful probes (objects of type `StatefulProbe`) are objects that can be marked either as "up" (healthy) or "down" (unhealthy) and provide a `ProbeFunction` for easy integration. Those objects utilize `sync.Mutex` mechanism to provide thread-safety.
|
|
|
|
```go
|
|
// Unhealthy by default
|
|
someProbe := kubeprobes.NewStatefulProbe()
|
|
someOtherProbe := kubeprobes.NewStatefulProbe()
|
|
|
|
// Use it in probes handler
|
|
kp, _ := kubeprobes.New(
|
|
kubeprobes.WithLivenessStatefulProbes(someProbe),
|
|
kubeprobes.WithReadinessStatefulProbes(someOtherProbe),
|
|
)
|
|
```
|
|
|
|
## Direct handler access
|
|
|
|
It is possible to fetch `http.Handler`s for liveness & readiness probes from `kubeprobes.Kubeprobes` instance as follows:
|
|
|
|
```go
|
|
kp, _ := kubeprobes.New(
|
|
// ...
|
|
)
|
|
|
|
livenessHandler := kp.GetLivenessHandler()
|
|
readinessHandler := kp.GetReadinessHandler()
|
|
```
|
|
|
|
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
|
|
|
|
```go
|
|
// Create probe functions
|
|
appProbe := func() error {
|
|
// Some logic for checking app status
|
|
return nil
|
|
}
|
|
|
|
// Create stateful probes
|
|
live := kubeprobes.NewStatefulProbe()
|
|
ready := kubeprobes.NewStatefulProbe()
|
|
|
|
// Prepare handler
|
|
kp, err := kubeprobes.New(
|
|
kubeprobes.WithLivenessStatefulProbes(live),
|
|
kubeprobes.WithReadinessStatefulProbes(ready),
|
|
kubeprobes.WithReadinessProbes(appProbe),
|
|
kubeprobes.WithLivenessPath("/livez"),
|
|
kubeprobes.WithReadinessPath("/readyz"),
|
|
)
|
|
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.MarkAsUp()
|
|
ready.MarkAsUp()
|
|
```
|