Compare commits

..

No commits in common. "b906789967f9724b227dd49d9a56b7c3a0711779" and "429db2d8ed1c10c78940de386ed41f4e7f318cfd" have entirely different histories.

12 changed files with 77 additions and 265 deletions

View File

@ -1,15 +1,3 @@
## [1.2.0-rc.1](https://git.ext.icikowski.pl/go/kubeprobes/compare/v1.1.0...v1.2.0-rc.1) (2024-03-01)
### Features
* **handlers:** add individual handlers fetching ([bb108ad](https://git.ext.icikowski.pl/go/kubeprobes/commit/bb108ad9baf7a14c7e39709a58987706a713d4ce))
### Refactoring
* **kubeprobes:** refactor code ([d33e9f1](https://git.ext.icikowski.pl/go/kubeprobes/commit/d33e9f19ea353cd320d584ad093c311f66eb1b28))
## [1.1.0](https://git.ext.icikowski.pl/go/kubeprobes/compare/v1.0.0...v1.1.0) (2024-02-29)

View File

@ -10,23 +10,19 @@ 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 package provides `kubeprobes.New` function which returns a probes handler 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.
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:
The `kubeprobes.New` function accepts following options-applying functions 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`).
- `kubeprobes.WithLivenessProbes(/* ... */)` - adds particular [probes](#probes) to the list of liveness probes;
- `kubeprobes.WithReadinessProbes(/* ... */)` - adds particular [probes](#probes) to the list of readiness probes.
## Probes
@ -51,7 +47,7 @@ someOtherProbe := func() error {
}
// Use functions in probes handler
kp, _ := kubeprobes.New(
kp := kubeprobes.New(
kubeprobes.WithLivenessProbes(someOtherProbe),
kubeprobes.WithReadinessProbes(someProbe),
)
@ -67,52 +63,24 @@ someProbe := kubeprobes.NewStatefulProbe()
someOtherProbe := kubeprobes.NewStatefulProbe()
// Use it in probes handler
kp, _ := kubeprobes.New(
kubeprobes.WithLivenessStatefulProbes(someProbe),
kubeprobes.WithReadinessStatefulProbes(someOtherProbe),
kp := kubeprobes.New(
kubeprobes.WithLivenessProbes(someProbe.GetProbeFunction()),
kubeprobes.WithReadinessProbes(someOtherProbe.GetProbeFunction()),
)
```
## 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"),
kp := kubeprobes.New(
kubeprobes.WithLivenessProbes(live.GetProbeFunction()),
kubeprobes.WithReadinessProbes(ready.GetProbeFunction()),
)
if err != nil {
// Kubeprobes object is validated for invalid or conflicting paths! ;)
panic(err)
}
// Start the probes server
probes := &http.Server{

View File

@ -2,6 +2,11 @@ package kubeprobes
import "sync"
// ProbeFunction is a function that determines whether
// the given metric may be marked as correctly functioning.
// It not, the error should be returned.
type ProbeFunction func() error
type statusQuery struct {
allGreen bool
mux sync.Mutex

View File

@ -1,7 +0,0 @@
package kubeprobes
const (
defaultLivenessPath string = "/live"
defaultReadinessPath string = "/ready"
verboseOutputFlag string = "v"
)

View File

@ -1,67 +0,0 @@
package kubeprobes
type option struct {
fn func(*kubeprobes)
}
func (o *option) apply(kp *kubeprobes) {
o.fn(kp)
}
// WithLivenessProbes adds given probe functions to the set of liveness probes.
func WithLivenessProbes(probes ...ProbeFunction) Option {
return &option{
fn: func(kp *kubeprobes) {
kp.livenessProbes = append(kp.livenessProbes, probes...)
},
}
}
// WithLivenessStatefulProbes adds given [StatefulProbe]s to the set of liveness probes.
func WithLivenessStatefulProbes(probes ...*StatefulProbe) Option {
return &option{
fn: func(kp *kubeprobes) {
for _, p := range probes {
kp.livenessProbes = append(kp.livenessProbes, p.GetProbeFunction())
}
},
}
}
// WithLivenessPath sets custom path for liveness probe (default is "/live").
func WithLivenessPath(path string) Option {
return &option{
fn: func(kp *kubeprobes) {
kp.pathLive = path
},
}
}
// WithReadinessProbes adds given probe functions to the set of readiness probes.
func WithReadinessProbes(probes ...ProbeFunction) Option {
return &option{
fn: func(kp *kubeprobes) {
kp.readinessProbes = append(kp.readinessProbes, probes...)
},
}
}
// WithReadinessProbes adds given [StatefulProbe]s to the set of readiness probes.
func WithReadinessStatefulProbes(probes ...*StatefulProbe) Option {
return &option{
fn: func(kp *kubeprobes) {
for _, p := range probes {
kp.readinessProbes = append(kp.readinessProbes, p.GetProbeFunction())
}
},
}
}
// WithReadinessPath sets custom path for readiness probe (default is "/ready").
func WithReadinessPath(path string) Option {
return &option{
fn: func(kp *kubeprobes) {
kp.pathReady = path
},
}
}

4
package-lock.json generated
View File

@ -1,12 +1,12 @@
{
"name": "kubeprobes",
"version": "1.2.0-rc.1",
"version": "1.1.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "kubeprobes",
"version": "1.2.0-rc.1",
"version": "1.1.0",
"devDependencies": {
"@saithodev/semantic-release-gitea": "^2.1.0",
"@semantic-release/changelog": "^6.0.3",

View File

@ -1,7 +1,7 @@
{
"private": true,
"name": "kubeprobes",
"version": "1.2.0-rc.1",
"version": "1.1.0",
"scripts": {
"release": "./node_modules/.bin/semantic-release"
},

146
probes.go
View File

@ -1,8 +1,6 @@
package kubeprobes
import (
"errors"
"fmt"
"net/http"
"strings"
)
@ -10,107 +8,57 @@ import (
type kubeprobes struct {
livenessProbes []ProbeFunction
readinessProbes []ProbeFunction
pathLive string
pathReady string
}
// New returns a new instance of a Kubernetes probes with given options.
func New(options ...Option) (Kubeprobes, error) {
kp := &kubeprobes{
livenessProbes: []ProbeFunction{},
readinessProbes: []ProbeFunction{},
pathLive: "/live",
pathReady: "/ready",
}
for _, option := range options {
option.apply(kp)
}
if err := kp.validate(); err != nil {
return nil, err
}
return kp, nil
}
func (kp *kubeprobes) validate() error {
errs := []error{}
if kp.pathLive == "" {
errs = append(
errs,
fmt.Errorf("liveness probe path must not be empty"),
)
}
if kp.pathReady == "" {
errs = append(
errs,
fmt.Errorf("readiness probe path must not be empty"),
)
}
if !strings.HasPrefix(kp.pathLive, "/") {
errs = append(
errs,
fmt.Errorf("liveness probe path must start with slash (current: %q)", kp.pathLive),
)
}
if !strings.HasPrefix(kp.pathReady, "/") {
errs = append(
errs,
fmt.Errorf("readiness probe path must start with slash (current: %q)", kp.pathReady),
)
}
if kp.pathLive == kp.pathReady {
errs = append(
errs,
fmt.Errorf("liveness and readiness probes have the same values (both %q)", kp.pathLive),
)
}
return errors.Join(errs...)
}
func (kp *kubeprobes) handleLiveness(w http.ResponseWriter, _ *http.Request) {
sq := newStatusQuery(kp.livenessProbes)
if sq.isAllGreen() {
w.WriteHeader(http.StatusOK)
} else {
w.WriteHeader(http.StatusServiceUnavailable)
}
}
func (kp *kubeprobes) handleReadiness(w http.ResponseWriter, _ *http.Request) {
sq := newStatusQuery(append(kp.livenessProbes, kp.readinessProbes...))
if sq.isAllGreen() {
w.WriteHeader(http.StatusOK)
} else {
w.WriteHeader(http.StatusServiceUnavailable)
}
}
// GetLivenessHandler implements Kubeprobes.
func (kp *kubeprobes) GetLivenessHandler() http.Handler {
return http.HandlerFunc(kp.handleLiveness)
}
// GetReadinessHandler implements Kubeprobes.
func (kp *kubeprobes) GetReadinessHandler() http.Handler {
return http.HandlerFunc(kp.handleReadiness)
}
// ServeHTTP implements Kubeprobes.
// ServeHTTP implements http.Handler interface
func (kp *kubeprobes) ServeHTTP(w http.ResponseWriter, r *http.Request) {
switch r.URL.Path {
case kp.pathLive:
kp.handleLiveness(w, r)
case kp.pathReady:
kp.handleReadiness(w, r)
subs := strings.Split(strings.TrimSuffix(r.URL.Path, "/"), "/")
switch subs[len(subs)-1] {
case "live":
sq := newStatusQuery(kp.livenessProbes)
if sq.isAllGreen() {
w.WriteHeader(http.StatusOK)
} else {
w.WriteHeader(http.StatusServiceUnavailable)
}
case "ready":
sq := newStatusQuery(append(kp.livenessProbes, kp.readinessProbes...))
if sq.isAllGreen() {
w.WriteHeader(http.StatusOK)
} else {
w.WriteHeader(http.StatusServiceUnavailable)
}
default:
w.WriteHeader(http.StatusNotFound)
}
}
type option func(*kubeprobes)
// New returns a new instance of a Kubernetes probes
func New(options ...option) *kubeprobes {
kp := &kubeprobes{
livenessProbes: []ProbeFunction{},
readinessProbes: []ProbeFunction{},
}
for _, option := range options {
option(kp)
}
return kp
}
// WithLivenessProbes adds given liveness probes to the set of probes
func WithLivenessProbes(probes ...ProbeFunction) option {
return func(kp *kubeprobes) {
kp.livenessProbes = append(kp.livenessProbes, probes...)
}
}
// WithReadinessProbes adds given readiness probes to the set of probes
func WithReadinessProbes(probes ...ProbeFunction) option {
return func(kp *kubeprobes) {
kp.readinessProbes = append(kp.readinessProbes, probes...)
}
}

View File

@ -50,9 +50,9 @@ func TestKubeprobes(t *testing.T) {
},
}
kp, _ := New(
WithLivenessStatefulProbes(live),
WithReadinessStatefulProbes(ready),
kp := New(
WithLivenessProbes(live.GetProbeFunction()),
WithReadinessProbes(ready.GetProbeFunction()),
)
srv := httptest.NewServer(kp)
@ -65,8 +65,8 @@ func TestKubeprobes(t *testing.T) {
test.livenessProbeTransformation(t, live)
test.readinessProbeTransformation(t, ready)
liveStatus := getStatusFromEndpoint(t, client, srv.URL+defaultLivenessPath)
readyStatus := getStatusFromEndpoint(t, client, srv.URL+defaultReadinessPath)
liveStatus := getStatusFromEndpoint(t, client, srv.URL+"/live")
readyStatus := getStatusFromEndpoint(t, client, srv.URL+"/ready")
otherStatus := getStatusFromEndpoint(t, client, srv.URL+"/something")
if liveStatus != test.expectedLiveStatus {

View File

@ -5,13 +5,13 @@ import (
"sync"
)
var errProbeDown = errors.New("probe is down")
var errProbeDown = errors.New("DOWN")
// StatefulProbe represents the simple probe that can be either
// marked as "up" (healthy) or "down" (unhealthy).
type StatefulProbe struct {
mux sync.Mutex
status bool
mux sync.Mutex
}
// NewStatefulProbe returns a new instance of a stateful probe
@ -19,19 +19,19 @@ type StatefulProbe struct {
// The probe is initially marked as "down".
func NewStatefulProbe() *StatefulProbe {
return &StatefulProbe{
mux: sync.Mutex{},
status: false,
mux: sync.Mutex{},
}
}
// MarkAsUp marks the probe as healthy.
// MarkAsUp marks the probe as healthy
func (sp *StatefulProbe) MarkAsUp() {
sp.mux.Lock()
defer sp.mux.Unlock()
sp.status = true
}
// MarkAsDown marks the probe as unhealthy.
// MarkAsDown marks the probe as unhealthy
func (sp *StatefulProbe) MarkAsDown() {
sp.mux.Lock()
defer sp.mux.Unlock()

View File

@ -1,23 +0,0 @@
package kubeprobes
import "net/http"
// Kubeprobes represents liveness & readiness probes handler.
type Kubeprobes interface {
http.Handler
// GetLivenessHandler returns [http.Handler] for liveness probes.
GetLivenessHandler() http.Handler
// GetReadinessHandler returns [http.Handler] for readiness probes.
GetReadinessHandler() http.Handler
}
// Option represents a [Kubeprobes] constructor option.
type Option interface {
apply(kp *kubeprobes)
}
// ProbeFunction is a function that determines whether
// the given metric may be marked as correctly functioning.
// It not, the error should be returned.
type ProbeFunction func() error