probes

README

Golang Kubernetes Probes Kit

Комплект разработчика для обслуживания проб Kubernetes.

Probes Kit: Введение для разработчиков

Контракты для Liveness-, Readiness- и Startup-проб Kubernetes.

Интеграция с Fiber.

Использование

Поддержка проб Kubernetes

Kubernetes Kit предоставляет контракт для реализации обработчиков запросов проб Kubernetes: Liveness, Readiness и Startup.

Для создания собственных обработчиков необходимо реализовать probes.Probes, который включает probes.Liveness, probes.Readiness и probes.Startup.

Пример контракта probes.Liveness:

package probes

type Liveness interface {
	Liveness(context.Context) (Result, error)
}

Все контракты обработчиков запросов проб оперируют probes.Result, предоставляющий несколько значений результата обработки запроса. Запрос может быть выполнен успешно, успешно с отладочной информацией и с ошибкой.

Интеграция с Fiber

Probes Kit интегрирован с Fiber.

Для всех проб существуют HTTP-обработчики Fiber: probes.FiberLiveness, probes.FiberReadiness, probes.FiberStartup.

Инициализация и запуск REST-сервера

package main

import (
	"fmt"
	"log"

	"github.com/gofiber/fiber/v2"

	"github.com/mlaymer/probes"
)

func main() {
	app := fiber.New()

	server := probes.Fiber(app).Probes(probes.DefaultProbes)

	log.Println(server.Start(probes.DefaultServerAddress))
}

Documentation

Index

• Constants
• Variables
• type FiberLiveness
  • func NewFiberLiveness(probe Liveness) FiberLiveness
  • func (handler FiberLiveness) Liveness(ctx *fiber.Ctx) error
• type FiberReadiness
  • func NewFiberReadiness(probe Readiness) FiberReadiness
  • func (handler FiberReadiness) Readiness(ctx *fiber.Ctx) error
• type FiberServer
  • func Fiber(app *fiber.App) *FiberServer
  • func (server *FiberServer) Probes(probes Probes) *FiberServer
  • func (server *FiberServer) Start(address string) error
• type FiberStartup
  • func NewFiberStartup(probe Startup) FiberStartup
  • func (handler FiberStartup) Startup(ctx *fiber.Ctx) error
• type Liveness
• type Probes
• type Readiness
• type Result
  • func (r Result) IsFailure() bool
  • func (r Result) IsSuccess() bool
  • func (r Result) IsWarning() bool
  • func (r Result) String() string
  • func (r Result) Validate() error
• type Startup
• type SuccessLiveness
  • func (probe SuccessLiveness) Liveness(context.Context) (Result, error)
• type SuccessProbes
  • func NewSuccessProbes() *SuccessProbes
  • func (probes *SuccessProbes) Liveness(ctx context.Context) (Result, error)
  • func (probes *SuccessProbes) Readiness(ctx context.Context) (Result, error)
  • func (probes *SuccessProbes) Startup(ctx context.Context) (Result, error)
• type SuccessReadiness
  • func (s SuccessReadiness) Readiness(context.Context) (Result, error)
• type SuccessStartup
  • func (probe SuccessStartup) Startup(context.Context) (Result, error)

Constants

const (
	// DefaultServerAddress содержит путь по умолчанию
	// REST-сервера для обработчиков проб Kubernetes.
	DefaultServerAddress = "localhost:9000"

	// DefaultLivenessPath содержит путь по умолчанию
	// для HTTP-обработчика Liveness-запросов Kubernetes.
	DefaultLivenessPath = "/liveness"

	// DefaultReadinessPath содержит путь по умолчанию
	// для HTTP-обработчика Readiness-запросов Kubernetes.
	DefaultReadinessPath = "/readiness"

	// DefaultStartupPath содержит путь по умолчанию
	// для HTTP-обработчика Startup-запросов Kubernetes.
	DefaultStartupPath = "/startup"
)

Variables

var DefaultFiberLiveness = NewFiberLiveness(DefaultLiveness)

DefaultFiberLiveness содержит инициализированный HTTP-обработчик Liveness-запроса Kubernetes.

Обработчик всегда возвращает HTTP 200 OK.

var DefaultFiberReadiness = NewFiberReadiness(DefaultReadiness)

DefaultFiberReadiness содержит инициализированный HTTP-обработчик Readiness-запроса Kubernetes.

Обработчик всегда возвращает HTTP 200 OK.

var DefaultFiberStartup = NewFiberStartup(DefaultStartup)

DefaultFiberStartup содержит инициализированный HTTP-обработчик Startup-запроса Kubernetes.

Обработчик всегда возвращает HTTP 200 OK.

var DefaultLiveness = SuccessLiveness{}

DefaultLiveness содержит обработчик Liveness-проб Kubernetes по умолчанию.

Обработчик по умолчанию – SuccessLiveness.

var DefaultProbes = NewSuccessProbes()

DefaultProbes содержит обработчики Liveness-, Readiness- и Startup-проб Kubernetes по-умолчанию.

Смотри DefaultLiveness, DefaultReadiness и DefaultStartup

var DefaultReadiness = SuccessReadiness{}

DefaultReadiness содержит обработчик Readiness-проб Kubernetes по умолчанию.

Обработчик по умолчанию – SuccessReadiness.

var DefaultStartup = SuccessStartup{}

DefaultStartup содержит обработчик Startup-проб Kubernetes по умолчанию.

Обработчик по умолчанию – SuccessStartup.

var ErrUnsupportedResult = errors.New("probes: unsupported result")

ErrUnsupportedResult указывает, что используемый результат в ответе эндпоинта не поддерживается.

Смотри Result

Types

type FiberLiveness

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

FiberLiveness обрабатывает HTTP-запросы Liveness Kubernetes.

Обработчику необходима реализация Liveness.

Для инициализации необходимо использовать метод NewFiberLiveness. Реализация по умолчанию – DefaultFiberLiveness.

func NewFiberLiveness

func NewFiberLiveness(probe Liveness) FiberLiveness

NewFiberLiveness инициализирует HTTP-обработчик Liveness-запросов Kubernetes на Fiber.

func (FiberLiveness) Liveness

func (handler FiberLiveness) Liveness(ctx *fiber.Ctx) error

Liveness обрабатывает HTTP-запрос Liveness от Kubernetes.

Если Liveness возвращает Success или Warning, то обработчик возвращает HTTP 200 OK с опциональным телом, если Failure – HTTP 500 Internal Server Error с опциональным телом.

type FiberReadiness

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

FiberReadiness обрабатывает HTTP-запросы Readiness Kubernetes.

Обработчику необходима реализация Readiness.

Для инициализации необходимо использовать метод NewFiberReadiness. Реализация по умолчанию – DefaultFiberReadiness.

func NewFiberReadiness

func NewFiberReadiness(probe Readiness) FiberReadiness

NewFiberReadiness инициализирует HTTP-обработчик Readiness-запросов Kubernetes на Fiber.

func (FiberReadiness) Readiness

func (handler FiberReadiness) Readiness(ctx *fiber.Ctx) error

Readiness обрабатывает HTTP-запрос Readiness от Kubernetes.

Если Readiness возвращает Success или Warning, то обработчик возвращает HTTP 200 OK с опциональным телом, если Failure – HTTP 500 Internal Server Error с опциональным телом.

type FiberServer

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

FiberServer содержит REST-эндпоинты для проб Kubernetes: Liveness, Readiness и Startup.

Для инициализации сервера необходим сначала вызвать метод Fiber с необходимыми параметрами.

func Fiber

func Fiber(app *fiber.App) *FiberServer

Fiber подготавливает REST-сервер для приёма Liveness-, Readiness- и Startup-проб.

После вызова метода следует вызвать метод FiberServer.Probes, который выполнит инициализацию REST-эндпоинтов.

func (*FiberServer) Probes

func (server *FiberServer) Probes(probes Probes) *FiberServer

Probes инициализирует REST-эндпоинты для Liveness-, Readiness- и Startup-проб Kubernetes.

Liveness-эндпоинт доступен по пути /liveness
Readiness-эндпоинт доступен по пути /readiness
Startup-эндпоинт доступен по пути /startup

func (*FiberServer) Start

func (server *FiberServer) Start(address string) error

Start запускает REST-сервер с пробами Kubernetes по указанному адресу.

type FiberStartup

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

FiberStartup обрабатывает HTTP-запросы Startup Kubernetes.

Обработчику необходима реализация Startup.

Для инициализации необходимо использовать метод NewFiberStartup. Реализация по умолчанию – DefaultFiberStartup.

func NewFiberStartup

func NewFiberStartup(probe Startup) FiberStartup

NewFiberStartup инициализирует HTTP-обработчик Startup-запросов Kubernetes на Fiber.

func (FiberStartup) Startup

func (handler FiberStartup) Startup(ctx *fiber.Ctx) error

Startup обрабатывает HTTP-запрос Startup от Kubernetes.

Если Startup возвращает Success или Warning, то обработчик возвращает HTTP 200 OK с опциональным телом, если Failure – HTTP 500 Internal Server Error с опциональным телом.

type Liveness

type Liveness interface {
	Liveness(context.Context) (Result, error)
}

Liveness оборачивает метод Liveness, который обрабатывает Liveness-запрос Kubernetes, используемый для определения нужно ли перезапускать контейнер.

Во время работы приложения накапливаются ошибки, которые исправляются только после перезапуска контейнера.

Метод возвращает Result и ошибку, которая содержит отладочную информацию.

type Probes

type Probes interface {
	Liveness
	Readiness
	Startup
}

Probes содержит контракты для реализации проб Kubernetes: Liveness, Readiness и Startup.

type Readiness

type Readiness interface {
	Readiness(context.Context) (Result, error)
}

Readiness оборачивает метод Readiness, который обрабатывает Readiness-запрос Kubernetes, используемый для определения готов ли контейнер принимать трафик.

Сигнал Readiness используется для включения пода в балансировщик нагрузки.

Метод возвращает Result и ошибку, которая содержит отладочную информацию.

type Result

type Result uint8

Result определяет результат, возвращаемый эндпоинтами Kubernetes: Liveness, Readiness и Startup.

Поддерживаемые статусы:
Success
Warning
Failure

const (
	// Success указывает на успешный ответ эндпоинта.
	Success Result = iota

	// Warning логически означает успешный ответ, но
	// с дополнительной отладочной информацией.
	Warning

	// Failure указывает на ответ с ошибкой от эндпоинта.
	Failure
)

func (Result) IsFailure

func (r Result) IsFailure() bool

IsFailure возвращает true, если результат равен Failure.

func (Result) IsSuccess

func (r Result) IsSuccess() bool

IsSuccess возвращает true, если результат равен Success.

func (Result) IsWarning

func (r Result) IsWarning() bool

IsWarning возвращает true, если результат равен Warning.

func (Result) String

func (r Result) String() string

func (Result) Validate

func (r Result) Validate() error

type Startup

type Startup interface {
	Startup(context.Context) (Result, error)
}

Startup оборачивает метод Startup, который обрабатывает Startup-метод Kubernetes, используемый для определения запущено ли приложение.

Если Kubernetes настроен на использование этой пробы, то пробы Liveness и Readiness отключаются до получения результата от Startup. Это сделано во избежание уничтожения их Kubernetes до момента окончательного старта. Используется в приложениях с медленным запуском.

Метод возвращает Result и ошибку, содержащую отладочную информацию.

type SuccessLiveness

type SuccessLiveness struct{}

SuccessLiveness реализует обработку Liveness-пробы Kubernetes с результатом Success.

Обработчик при любых обстоятельствах возвращает именно этот результат, ошибка в ответе отсутствует.

func (SuccessLiveness) Liveness

func (probe SuccessLiveness) Liveness(context.Context) (Result, error)

type SuccessProbes

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

SuccessProbes содержит реализации проб Kubernetes, которые возвращают всегда положительный результат.

Смотри SuccessLiveness, SuccessReadiness, SuccessStartup

func NewSuccessProbes

func NewSuccessProbes() *SuccessProbes

NewSuccessProbes инициализирует пробы Kubernetes, которые возвращают всегда положительный результат.

func (*SuccessProbes) Liveness

func (probes *SuccessProbes) Liveness(ctx context.Context) (Result, error)

func (*SuccessProbes) Readiness

func (probes *SuccessProbes) Readiness(ctx context.Context) (Result, error)

func (*SuccessProbes) Startup

func (probes *SuccessProbes) Startup(ctx context.Context) (Result, error)

type SuccessReadiness

type SuccessReadiness struct{}

SuccessReadiness реализует обработку Readiness-пробы Kubernetes с результатом Success.

Обработчик при любых обстоятельствах возвращает именно этот результат, ошибка в ответе отсутствует.

func (SuccessReadiness) Readiness

func (s SuccessReadiness) Readiness(context.Context) (Result, error)

type SuccessStartup

type SuccessStartup struct{}

SuccessStartup реализует обработку Startup-пробы Kubernetes с результатом Success.

Обработчик при любых обстоятельствах возвращает именно этот результат, ошибка в ответе отсутствует.

func (SuccessStartup) Startup

func (probe SuccessStartup) Startup(context.Context) (Result, error)