xpod

Documentation

Overview

Package xpod contains utilities that help implement best practices for health checks and more, while building go apps for kubernetes pods.

Health checker source comes from k8s.io/apiserver/pkg/server/healthz/healthz.go

Index

• type BuildDate
  • func (d BuildDate) MarshalJSON() ([]byte, error)
  • func (d BuildDate) String() string
• type BuildInfo
• type Checker
• type CheckerFun
  • func CheckerFunc(name string, check func(*http.Request) error) *CheckerFun
  • func (f *CheckerFun) Check(req *http.Request) error
  • func (f *CheckerFun) Name() string
• type Options
• type ProbeHandler
  • func NewProbeHandler(opts Options) *ProbeHandler
  • func (h *ProbeHandler) HealthHandler() http.Handler
  • func (h *ProbeHandler) ReadyHandler() http.Handler
  • func (h *ProbeHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (h *ProbeHandler) VersionHandler() http.Handler

Examples

• NewProbeHandler
• NewProbeHandler (WithoutManagedServeMux)

Types

type BuildDate

type BuildDate time.Time

BuildDate is an alias to time.Time.

func (BuildDate) MarshalJSON

func (d BuildDate) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (BuildDate) String

func (d BuildDate) String() string

type BuildInfo

type BuildInfo struct {
	Version   string    `json:"version"`
	Tag       string    `json:"tag"`
	Commit    string    `json:"commit"`
	BuildDate BuildDate `json:"build_date"`
}

BuildInfo holds the information about current build.

type Checker

type Checker interface {
	Name() string
	Check(r *http.Request) error
}

Checker is a named resource/component checker.

var PingHealthz Checker = ping{}

PingHealthz returns true automatically when checked.

type CheckerFun

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

CheckerFun implements Checker interface.

func CheckerFunc

func CheckerFunc(name string, check func(*http.Request) error) *CheckerFun

CheckerFunc implements Checker interface.

func (*CheckerFun) Check

func (f *CheckerFun) Check(req *http.Request) error

Check is used to invoke health check when a request is received.

func (*CheckerFun) Name

func (f *CheckerFun) Name() string

Name returns the name of the health check.

type Options

type Options struct {
	HealthCheckers []Checker
	ReadyCheckers  []Checker
	BuildInfo      *BuildInfo

	// Prefix is the base path for the health, ready, and version endpoints.
	// If not provided, the default value is "/".
	// If the prefix is "/probe", the health, ready, and version endpoints
	// will be available at:
	// - /probe/healthz
	// - /probe/readyz
	// - /probe/version
	//
	// HealthPath is the path for the health endpoint.
	// If not provided, the default value is "healthz".
	//
	// ReadyPath is the path for the readiness endpoint.
	// If not provided, the default value is "readyz".
	//
	// VersionPath is the path for the version endpoint.
	// If not provided, the default value is "version".
	//
	// Note: Prefix, HealthPath, ReadyPath, and VersionPath are only used
	// for internal http.ServeMux registration.
	Prefix, HealthPath, ReadyPath, VersionPath string

	ErrorLogDelegate func(string, map[string]any)

	// ShowErrReasons is used to show the error reasons in the HTTP response.
	ShowErrReasons bool
}

Options can be used to provide custom health/readiness checkers and the current BuildInfo.

type ProbeHandler

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

ProbeHandler implements http.Handler interface to expose [/healthz /readyz /version] endpoints.

func NewProbeHandler

func NewProbeHandler(opts Options) *ProbeHandler

NewProbeHandler returns a http.Handler which can be used to serve health check and build info endpoints.

Example

package main

import (
	"net/http"
	"time"

	"github.com/gojekfarm/xtools/xpod"
)

func main() {
	h := http.NewServeMux()

	// This method automatically registers the health, ready, and version endpoints
	// with the provided prefix.
	// If you want to register the endpoints with a custom path, you can use the
	// `HealthHandler`, `ReadyHandler`, and `VersionHandler` methods. See the examples below.
	h.Handle("/probe", xpod.NewProbeHandler(xpod.Options{
		Prefix: "/probe",
		BuildInfo: &xpod.BuildInfo{
			Version:   "0.1.0",
			Tag:       "v0.1.0",
			Commit:    "24b3f5d876ffa402287bfa5c26cf05626a2b3b01",
			BuildDate: xpod.BuildDate(time.Now()),
		},
	}))
}

Example (WithoutManagedServeMux)

package main

import (
	"net/http"
	"time"

	"github.com/gojekfarm/xtools/xpod"
)

func main() {
	h := http.NewServeMux()

	ph := xpod.NewProbeHandler(xpod.Options{
		Prefix: "/probe",
		BuildInfo: &xpod.BuildInfo{
			Version:   "0.1.0",
			Tag:       "v0.1.0",
			Commit:    "24b3f5d876ffa402287bfa5c26cf05626a2b3b01",
			BuildDate: xpod.BuildDate(time.Now()),
		},
	})

	h.Handle("/health", ph.HealthHandler())
	h.Handle("/ready", ph.ReadyHandler())
	h.Handle("/version", ph.VersionHandler())
}

func (*ProbeHandler) HealthHandler

func (h *ProbeHandler) HealthHandler() http.Handler

HealthHandler returns the handler for the health endpoint.

func (*ProbeHandler) ReadyHandler

func (h *ProbeHandler) ReadyHandler() http.Handler

ReadyHandler returns the handler for the readiness endpoint.

func (*ProbeHandler) ServeHTTP

func (h *ProbeHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*ProbeHandler) VersionHandler

func (h *ProbeHandler) VersionHandler() http.Handler

VersionHandler returns the handler for the version endpoint. Note: It will be nil if the Options.BuildInfo is not provided.