webserver

Documentation

Index

• type CompletedConfig
  • func (c CompletedConfig) New(name string) (*WebServer, error)
• type Config
  • func NewConfig() *Config
  • func (c *Config) AddHealthChecks(healthChecks ...healthz.HealthCheck)
  • func (c *Config) AddPostStartHook(name string, hook PostStartHookFunc) error
  • func (c *Config) AddPostStartHookOrDie(name string, hook PostStartHookFunc)
  • func (s *Config) AddPreShutdownHook(name string, hook PreShutdownHookFunc) error
  • func (s *Config) AddPreShutdownHookOrDie(name string, hook PreShutdownHookFunc)
  • func (c *Config) AddWebHandler(handlers ...WebHandler)
  • func (c *Config) Complete() CompletedConfig
• type PostStartHookFunc
• type PostStartHookProvider
• type PreShutdownHookFunc
• type WebHandler
• type WebServer
  • func (s *WebServer) AddBootSequenceHealthChecks(checks ...healthz.HealthCheck) error
  • func (s *WebServer) AddHealthChecks(checks ...healthz.HealthCheck) error
  • func (s *WebServer) AddPostStartHook(name string, hook PostStartHookFunc) error
  • func (s *WebServer) AddPostStartHookOrDie(name string, hook PostStartHookFunc)
  • func (s *WebServer) AddPreShutdownHook(name string, hook PreShutdownHookFunc) error
  • func (s *WebServer) AddPreShutdownHookOrDie(name string, hook PreShutdownHookFunc)
  • func (s *WebServer) PrepareRun() (preparedWebServer, error)
  • func (s *WebServer) RunPostStartHooks(ctx context.Context)
  • func (s *WebServer) RunPreShutdownHooks() error

Types

type CompletedConfig

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

func (CompletedConfig) New

func (c CompletedConfig) New(name string) (*WebServer, error)

New creates a new server which logically combines the handling chain with the passed server. name is used to differentiate for logging. The handler chain in particular can be difficult as it starts delgating.

type Config

type Config struct {
	GatewayOptions []grpc.GatewayOption
	GinMiddlewares []gin.HandlerFunc

	CORS *cors.Config

	TlsConfig *tls.Config

	ServiceRegistryBackend *consul.ServiceRegistryServer

	WebHandlers []WebHandler

	// done values in this values for this map are ignored.
	PostStartHooks   map[string]postStartHookEntry
	PreShutdownHooks map[string]preShutdownHookEntry

	// BindAddress is the host name to use for bind (local internet) facing URLs (e.g. Loopback)
	// Will default to a value based on secure serving info and available ipv4 IPs.
	BindAddress string
	// ExternalAddress is the host name to use for external (public internet) facing URLs (e.g. Swagger)
	// Will default to a value based on secure serving info and available ipv4 IPs.
	ExternalAddress string

	// The default set of healthz checks. There might be more added via AddHealthChecks dynamically.
	HealthzChecks []healthz.HealthCheck
	// The default set of livez checks. There might be more added via AddHealthChecks dynamically.
	LivezChecks []healthz.HealthCheck
	// The default set of readyz-only checks. There might be more added via AddReadyzChecks dynamically.
	ReadyzChecks []healthz.HealthCheck
	// ShutdownDelayDuration allows to block shutdown for some time, e.g. until endpoints pointing to this API server
	// have converged on all node. During this time, the API server keeps serving, /healthz will return 200,
	// but /readyz will return failure.
	ShutdownDelayDuration time.Duration
}

func NewConfig

func NewConfig() *Config

NewConfig returns a Config struct with the default values

func (*Config) AddHealthChecks

func (c *Config) AddHealthChecks(healthChecks ...healthz.HealthCheck)

AddHealthChecks adds a health check to our config to be exposed by the health endpoints of our configured webserver. We should prefer this to adding healthChecks directly to the config unless we explicitly want to add a healthcheck only to a specific health endpoint.

func (*Config) AddPostStartHook

func (c *Config) AddPostStartHook(name string, hook PostStartHookFunc) error

AddPostStartHook allows you to add a PostStartHook that will later be added to the server itself in a New call. Name conflicts will cause an error.

func (*Config) AddPostStartHookOrDie

func (c *Config) AddPostStartHookOrDie(name string, hook PostStartHookFunc)

AddPostStartHookOrDie allows you to add a PostStartHook, but dies on failure.

func (*Config) AddPreShutdownHook

func (s *Config) AddPreShutdownHook(name string, hook PreShutdownHookFunc) error

AddPreShutdownHook allows you to add a PreShutdownHook.

func (*Config) AddPreShutdownHookOrDie

func (s *Config) AddPreShutdownHookOrDie(name string, hook PreShutdownHookFunc)

AddPreShutdownHookOrDie allows you to add a PostStartHook, but dies on failure

func (*Config) AddWebHandler

func (c *Config) AddWebHandler(handlers ...WebHandler)

AddWebHandler adds a grpc and/or gin handler to our config to be exposed by the grpc gateway endpoints of our configured webserver.

func (*Config) Complete

func (c *Config) Complete() CompletedConfig

Complete fills in any fields not set that are required to have valid data and can be derived from other fields. If you're going to `ApplyOptions`, do that first. It's mutating the receiver.

type PostStartHookFunc

type PostStartHookFunc func(ctx context.Context) error

PostStartHookFunc is a function that is called after the server has started. It must properly handle cases like:

1. asynchronous start in multiple API server processes
2. conflicts between the different processes all trying to perform the same action
3. partially complete work (API server crashes while running your hook)
4. API server access **BEFORE** your hook has completed

Think of it like a mini-controller that is super privileged and gets to run in-process If you use this feature, tag @deads2k on github who has promised to review code for anyone's PostStartHook until it becomes easier to use.

type PostStartHookProvider

type PostStartHookProvider interface {
	PostStartHook() (string, PostStartHookFunc, error)
}

PostStartHookProvider is an interface in addition to provide a post start hook for the api server

type PreShutdownHookFunc

type PreShutdownHookFunc func() error

PreShutdownHookFunc is a function that can be added to the shutdown logic.

type WebHandler

type WebHandler interface {
	SetRoutes(ginRouter gin.IRouter, grpcRouter *grpc.Gateway)
}

type WebServer

type WebServer struct {
	Name string
	// Server Register. The backend is started after the server starts listening.
	ServiceRegistryBackend *consul.ServiceRegistryServer

	// ShutdownDelayDuration allows to block shutdown for some time, e.g. until endpoints pointing to this API server
	// have converged on all node. During this time, the API server keeps serving, /healthz will return 200,
	// but /readyz will return failure.
	ShutdownDelayDuration time.Duration
	// contains filtered or unexported fields
}

func (*WebServer) AddBootSequenceHealthChecks

func (s *WebServer) AddBootSequenceHealthChecks(checks ...healthz.HealthCheck) error

AddBootSequenceHealthChecks adds health checks to the old healthz endpoint (for backwards compatibility reasons) as well as livez and readyz. The livez grace period is defined by the value of the command-line flag --livez-grace-period; before the grace period elapses, the livez health checks will default to healthy. One may want to set a grace period in order to prevent the kubelet from restarting the kube-apiserver due to long-ish boot sequences. Readyz health checks, on the other hand, have no grace period, since readyz should fail until boot fully completes.

func (*WebServer) AddHealthChecks

func (s *WebServer) AddHealthChecks(checks ...healthz.HealthCheck) error

AddHealthChecks adds HealthCheck(s) to health endpoints (healthz, livez, readyz) but configures the liveness grace period to be zero, which means we expect this health check to immediately indicate that the apiserver is unhealthy.

func (*WebServer) AddPostStartHook

func (s *WebServer) AddPostStartHook(name string, hook PostStartHookFunc) error

AddPostStartHook allows you to add a PostStartHook.

func (*WebServer) AddPostStartHookOrDie

func (s *WebServer) AddPostStartHookOrDie(name string, hook PostStartHookFunc)

AddPostStartHookOrDie allows you to add a PostStartHook, but dies on failure

func (*WebServer) AddPreShutdownHook

func (s *WebServer) AddPreShutdownHook(name string, hook PreShutdownHookFunc) error

AddPreShutdownHook allows you to add a PreShutdownHook.

func (*WebServer) AddPreShutdownHookOrDie

func (s *WebServer) AddPreShutdownHookOrDie(name string, hook PreShutdownHookFunc)

AddPreShutdownHookOrDie allows you to add a PostStartHook, but dies on failure

func (*WebServer) PrepareRun

func (s *WebServer) PrepareRun() (preparedWebServer, error)

PrepareRun does post API installation setup steps. It calls recursively the same function of the delegates.

func (*WebServer) RunPostStartHooks

func (s *WebServer) RunPostStartHooks(ctx context.Context)

RunPostStartHooks runs the PostStartHooks for the server

func (*WebServer) RunPreShutdownHooks

func (s *WebServer) RunPreShutdownHooks() error

RunPreShutdownHooks runs the PreShutdownHooks for the server