kubestatus

package module
v0.0.0-...-17f204d Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 5, 2018 License: Apache-2.0 Imports: 12 Imported by: 0

README

go-kubestatus

Simplistic opinionated HTTP status server library designed to be provided a bare minimum of configuration (intended for Kubernetes).

https://godoc.org/github.com/joeycumines/go-kubestatus

  • Sets up a HTTP server that serves /readiness and /healthz endpoints
  • Provides a client implementation supporting multiple instances
  • Configurable bind port / hostname (uses https://github.com/gin-gonic/gin)
  • Allows overriding gin handlers
  • The status of both endpoints are defined by callbacks in the form func() error
  • Standard response object documented by swagger.yml, which includes UUID for the process
  • The /readiness endpoint can be automatically extended to check for the /readiness of other services via simple dependency config
  • Circular reference detection is in-built for /readiness, and automatically wired up if used via the dependency config
  • Exposes a context and fatal error info that can be used to handle fatal errors with the server including panics

The tests are very bad but complete-ish.

Documentation

Overview

Package status provides a simple, opinionated, kubernetes status http server.

Index

Constants

View Source
const (
	DefaultPort      = 8080
	DefaultStartWait = time.Millisecond * 100
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Client

type Client struct {
	// Addresses indicates a list of addresses to Get
	Addresses []string

	// All, if set to true, will try to Get all addresses regardless of any errors
	All bool

	// UUIDs will be passed in via the query parameter
	UUIDs []string
}

Client provides an interface to the server, for nested readiness checks, for example, providing short-circuiting logic, where the first failure status is returned

func (Client) Get

func (c Client) Get(endpoint string) ([]*Status, error)

Get hits the endpoint on all clients, and returns any statuses (if valid json responses are returned and can be deserialized), a non-nil error will be returned if any clients return a status not in the 200 range.

func (Client) Health

func (c Client) Health() ([]*Status, error)

Health hits `/healthz` returns a status slice of equal length to the addresses, with returned statuses for each (or nil), and the first error encountered (if any)

func (Client) Readiness

func (c Client) Readiness() ([]*Status, error)

Readiness hits `/readiness` returns a status slice of equal length to the addresses, with returned statuses for each (or nil), and the first error encountered (if any)

type Config

type Config struct {
	// Port is the tcp port to serve the http server
	Port int

	// Hostname is the hostname fragment for the http server, which defaults to an empty string (all)
	Hostname string

	// StartWait is how long the kubestatus.Service.Start operation will block after starting the server
	StartWait time.Duration

	// HealthHandler should return an error if the service is not ready
	HealthHandler HealthHandler

	// ReadinessHandler should return an error if the service is not ready
	ReadinessHandler ReadinessHandler

	// GinHandlers defines middleware to use
	GinHandlers []gin.HandlerFunc

	// Dependencies should be an array of addresses (including scheme) that are the root part of `/readiness`
	// endpoints, note that the `uuids` query parameter will be set, appending configured service's UUID on the
	// end of any existing `uuids` passed in with the original `/readiness` GET
	Dependencies []string

	// UUID may be set to override the UUID used for this service, a zero value will auto-generate.
	UUID [16]byte
}

Config provides configuration of the status http server.

func NewConfig

func NewConfig() Config

NewConfig creates a default config

func (Config) URL

func (c Config) URL() string

URL returns the HTTP url this service will bind on (an empty host defaults to localhost), it has a http scheme

func (Config) Validate

func (c Config) Validate() error

Validate returns an error if config is invalid

type FatalError

type FatalError struct {
	Error   error
	Time    time.Time
	Runtime time.Duration
}

FatalError models an error that occurred within the service, a non-nil Error would indicate that the server is stopped.

type HealthHandler

type HealthHandler func() error

HealthHandler should return an error if the service is not ready

type ReadinessHandler

type ReadinessHandler func() error

ReadinessHandler should return an error if the service is not ready

type Service

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

Service is an instance of the status server

func NewService

func NewService(config Config) (*Service, error)

NewService constructs a new status.Service

func (*Service) Ctx

func (s *Service) Ctx() context.Context

Ctx return the service's context, which will cancel once the service has been started then stopped

func (*Service) Fatal

func (s *Service) Fatal() FatalError

Fatal returns any fatal error that occurred within the service

func (*Service) Health

func (s *Service) Health() Status

Health returns the health of the service

func (*Service) Readiness

func (s *Service) Readiness(UUIDs ...string) Status

Readiness returns the readiness of the service, taking any number of previous UUIDs (oldest first)

func (*Service) Start

func (s *Service) Start() error

Start initialises the http server, may only happen once, and runs the http server in the background

func (*Service) UUID

func (s *Service) UUID() [16]byte

UUID returns this service's UUID

func (*Service) Validate

func (s *Service) Validate() error

Validate returns an error if the service wasn't initialised properly

type Status

type Status struct {
	// Code is the HTTP status code
	Code int `json:"code"`

	// Message will be either 'OK', or the error message
	Message string `json:"message"`

	// Success will be bool set to false for anything but 200
	Success bool `json:"success"`

	// Started is a nanoseconds epoch indicating when the service was started
	Started int64 `json:"started"`

	// Uptime is a human readable string representation of the current timestamp - started
	Uptime string `json:"uptime"`

	// UUID is a per-process uuid value in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
	UUID string `json:"uuid"`
}

Status is the response object returned by all endpoints

func NewStatus

func NewStatus(uuid [16]byte, started time.Time, err error) Status

NewStatus creates a new Status

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL