plan

Documentation

Index

• func CommandString(base, extra []string) string
• type Check
  • func (c *Check) Copy() *Check
  • func (c *Check) Merge(other *Check)
• type CheckLevel
• type ContextOptions
  • func MergeServiceContext(p *Plan, serviceName string, overrides ContextOptions) (ContextOptions, error)
• type ExecCheck
  • func (c *ExecCheck) Copy() *ExecCheck
  • func (c *ExecCheck) Merge(other *ExecCheck)
• type FormatError
  • func (e *FormatError) Error() string
• type HTTPCheck
  • func (c *HTTPCheck) Copy() *HTTPCheck
  • func (c *HTTPCheck) Merge(other *HTTPCheck)
• type Layer
  • func CombineLayers(layers ...*Layer) (*Layer, error)
  • func ParseLayer(order int, label string, data []byte) (*Layer, error)
  • func ReadLayersDir(dirname string) ([]*Layer, error)
  • func (layer *Layer) Validate() error
• type LogTarget
  • func (t *LogTarget) Copy() *LogTarget
  • func (t *LogTarget) Merge(other *LogTarget)
• type LogTargetType
• type OptionalDuration
  • func (o OptionalDuration) IsZero() bool
  • func (o OptionalDuration) MarshalYAML() (interface{}, error)
  • func (o *OptionalDuration) UnmarshalYAML(value *yaml.Node) error
• type OptionalFloat
  • func (o OptionalFloat) IsZero() bool
  • func (o OptionalFloat) MarshalYAML() (interface{}, error)
  • func (o *OptionalFloat) UnmarshalYAML(value *yaml.Node) error
• type Override
• type Plan
  • func ReadDir(dir string) (*Plan, error)
  • func (p *Plan) StartOrder(names []string) ([]string, error)
  • func (p *Plan) StopOrder(names []string) ([]string, error)
  • func (p *Plan) Validate() error
• type Service
  • func (s *Service) Copy() *Service
  • func (s *Service) Equal(other *Service) bool
  • func (s *Service) LogsTo(t *LogTarget) bool
  • func (s *Service) Merge(other *Service)
  • func (s *Service) ParseCommand() (base, extra []string, err error)
• type ServiceAction
• type ServiceStartup
• type TCPCheck
  • func (c *TCPCheck) Copy() *TCPCheck
  • func (c *TCPCheck) Merge(other *TCPCheck)

Functions

func CommandString

func CommandString(base, extra []string) string

CommandString returns a service command as a string after appending the arguments in "extra" to the command in "base"

Types

type Check

type Check struct {
	// Basic details
	Name     string     `yaml:"-"`
	Override Override   `yaml:"override,omitempty"`
	Level    CheckLevel `yaml:"level,omitempty"`

	// Common check settings
	Period    OptionalDuration `yaml:"period,omitempty"`
	Timeout   OptionalDuration `yaml:"timeout,omitempty"`
	Threshold int              `yaml:"threshold,omitempty"`

	// Type-specific check settings (only one of these can be set)
	HTTP *HTTPCheck `yaml:"http,omitempty"`
	TCP  *TCPCheck  `yaml:"tcp,omitempty"`
	Exec *ExecCheck `yaml:"exec,omitempty"`
}

Check specifies configuration for a single health check.

func (*Check) Copy

func (c *Check) Copy() *Check

Copy returns a deep copy of the check configuration.

func (*Check) Merge

func (c *Check) Merge(other *Check)

Merge merges the fields set in other into c.

type CheckLevel

type CheckLevel string

CheckLevel specifies the optional check level.

const (
	UnsetLevel CheckLevel = ""
	AliveLevel CheckLevel = "alive"
	ReadyLevel CheckLevel = "ready"
)

type ContextOptions

type ContextOptions struct {
	Environment map[string]string
	UserID      *int
	User        string
	GroupID     *int
	Group       string
	WorkingDir  string
}

ContextOptions holds service context config fields.

func MergeServiceContext

func MergeServiceContext(p *Plan, serviceName string, overrides ContextOptions) (ContextOptions, error)

MergeServiceContext merges the overrides on top of the service context specified by serviceName, returning a new ContextOptions value. If serviceName is "" (context not specified), return overrides directly.

type ExecCheck

type ExecCheck struct {
	Command        string            `yaml:"command,omitempty"`
	ServiceContext string            `yaml:"service-context,omitempty"`
	Environment    map[string]string `yaml:"environment,omitempty"`
	UserID         *int              `yaml:"user-id,omitempty"`
	User           string            `yaml:"user,omitempty"`
	GroupID        *int              `yaml:"group-id,omitempty"`
	Group          string            `yaml:"group,omitempty"`
	WorkingDir     string            `yaml:"working-dir,omitempty"`
}

ExecCheck holds the configuration for an exec health check.

func (*ExecCheck) Copy

func (c *ExecCheck) Copy() *ExecCheck

Copy returns a deep copy of the exec check configuration.

func (*ExecCheck) Merge

func (c *ExecCheck) Merge(other *ExecCheck)

Merge merges the fields set in other into c.

type FormatError

type FormatError struct {
	Message string
}

FormatError is the error returned when a layer has a format error, such as a missing "override" field.

func (*FormatError) Error

func (e *FormatError) Error() string

type HTTPCheck

type HTTPCheck struct {
	URL     string            `yaml:"url,omitempty"`
	Headers map[string]string `yaml:"headers,omitempty"`
}

HTTPCheck holds the configuration for an HTTP health check.

func (*HTTPCheck) Copy

func (c *HTTPCheck) Copy() *HTTPCheck

Copy returns a deep copy of the HTTP check configuration.

func (*HTTPCheck) Merge

func (c *HTTPCheck) Merge(other *HTTPCheck)

Merge merges the fields set in other into c.

type Layer

type Layer struct {
	Order       int                   `yaml:"-"`
	Label       string                `yaml:"-"`
	Summary     string                `yaml:"summary,omitempty"`
	Description string                `yaml:"description,omitempty"`
	Services    map[string]*Service   `yaml:"services,omitempty"`
	Checks      map[string]*Check     `yaml:"checks,omitempty"`
	LogTargets  map[string]*LogTarget `yaml:"log-targets,omitempty"`
}

func CombineLayers

func CombineLayers(layers ...*Layer) (*Layer, error)

CombineLayers combines the given layers into a single layer, with the later layers overriding earlier ones. Neither the individual layers nor the combined layer are validated here - the caller should have validated the individual layers prior to calling, and validate the combined output if required.

func ParseLayer

func ParseLayer(order int, label string, data []byte) (*Layer, error)

func ReadLayersDir

func ReadLayersDir(dirname string) ([]*Layer, error)

func (*Layer) Validate

func (layer *Layer) Validate() error

Validate checks that the layer is valid. It returns nil if all the checks pass, or an error if there are validation errors. See also Plan.Validate, which does additional checks based on the combined layers.

type LogTarget

type LogTarget struct {
	Name     string            `yaml:"-"`
	Type     LogTargetType     `yaml:"type"`
	Location string            `yaml:"location"`
	Services []string          `yaml:"services"`
	Override Override          `yaml:"override,omitempty"`
	Labels   map[string]string `yaml:"labels,omitempty"`
}

LogTarget specifies a remote server to forward logs to.

func (*LogTarget) Copy

func (t *LogTarget) Copy() *LogTarget

Copy returns a deep copy of the log target configuration.

func (*LogTarget) Merge

func (t *LogTarget) Merge(other *LogTarget)

Merge merges the fields set in other into t.

type LogTargetType

type LogTargetType string

LogTargetType defines the protocol to use to forward logs.

const (
	LokiTarget     LogTargetType = "loki"
	SyslogTarget   LogTargetType = "syslog"
	UnsetLogTarget LogTargetType = ""
)

type OptionalDuration

type OptionalDuration struct {
	Value time.Duration
	IsSet bool
}

func (OptionalDuration) IsZero

func (o OptionalDuration) IsZero() bool

func (OptionalDuration) MarshalYAML

func (o OptionalDuration) MarshalYAML() (interface{}, error)

func (*OptionalDuration) UnmarshalYAML

func (o *OptionalDuration) UnmarshalYAML(value *yaml.Node) error

type OptionalFloat

type OptionalFloat struct {
	Value float64
	IsSet bool
}

func (OptionalFloat) IsZero

func (o OptionalFloat) IsZero() bool

func (OptionalFloat) MarshalYAML

func (o OptionalFloat) MarshalYAML() (interface{}, error)

func (*OptionalFloat) UnmarshalYAML

func (o *OptionalFloat) UnmarshalYAML(value *yaml.Node) error

type Override

type Override string

Override specifies the layer override mechanism for an object.

const (
	UnknownOverride Override = ""
	MergeOverride   Override = "merge"
	ReplaceOverride Override = "replace"
)

type Plan

type Plan struct {
	Layers     []*Layer              `yaml:"-"`
	Services   map[string]*Service   `yaml:"services,omitempty"`
	Checks     map[string]*Check     `yaml:"checks,omitempty"`
	LogTargets map[string]*LogTarget `yaml:"log-targets,omitempty"`
}

func ReadDir

func ReadDir(dir string) (*Plan, error)

ReadDir reads the configuration layers from the "layers" sub-directory in dir, and returns the resulting Plan. If the "layers" sub-directory doesn't exist, it returns a valid Plan with no layers.

func (*Plan) StartOrder

func (p *Plan) StartOrder(names []string) ([]string, error)

StartOrder returns the required services that must be started for the named services to be properly started, in the order that they must be started. An error is returned when a provided service name does not exist, or there is an order cycle involving the provided service or its dependencies.

func (*Plan) StopOrder

func (p *Plan) StopOrder(names []string) ([]string, error)

StopOrder returns the required services that must be stopped for the named services to be properly stopped, in the order that they must be stopped. An error is returned when a provided service name does not exist, or there is an order cycle involving the provided service or its dependencies.

func (*Plan) Validate

func (p *Plan) Validate() error

Validate checks that the combined layers form a valid plan. See also Layer.Validate, which checks that the individual layers are valid.

type Service

type Service struct {
	// Basic details
	Name        string         `yaml:"-"`
	Summary     string         `yaml:"summary,omitempty"`
	Description string         `yaml:"description,omitempty"`
	Startup     ServiceStartup `yaml:"startup,omitempty"`
	Override    Override       `yaml:"override,omitempty"`
	Command     string         `yaml:"command,omitempty"`

	// Service dependencies
	After    []string `yaml:"after,omitempty"`
	Before   []string `yaml:"before,omitempty"`
	Requires []string `yaml:"requires,omitempty"`

	// Options for command execution
	Environment map[string]string `yaml:"environment,omitempty"`
	UserID      *int              `yaml:"user-id,omitempty"`
	User        string            `yaml:"user,omitempty"`
	GroupID     *int              `yaml:"group-id,omitempty"`
	Group       string            `yaml:"group,omitempty"`
	WorkingDir  string            `yaml:"working-dir,omitempty"`

	// Auto-restart and backoff functionality
	OnSuccess      ServiceAction            `yaml:"on-success,omitempty"`
	OnFailure      ServiceAction            `yaml:"on-failure,omitempty"`
	OnCheckFailure map[string]ServiceAction `yaml:"on-check-failure,omitempty"`
	BackoffDelay   OptionalDuration         `yaml:"backoff-delay,omitempty"`
	BackoffFactor  OptionalFloat            `yaml:"backoff-factor,omitempty"`
	BackoffLimit   OptionalDuration         `yaml:"backoff-limit,omitempty"`
	KillDelay      OptionalDuration         `yaml:"kill-delay,omitempty"`
}

func (*Service) Copy

func (s *Service) Copy() *Service

Copy returns a deep copy of the service.

func (*Service) Equal

func (s *Service) Equal(other *Service) bool

Equal returns true when the two services are equal in value.

func (*Service) LogsTo

func (s *Service) LogsTo(t *LogTarget) bool

LogsTo returns true if the logs from s should be forwarded to target t.

func (*Service) Merge

func (s *Service) Merge(other *Service)

Merge merges the fields set in other into s.

func (*Service) ParseCommand

func (s *Service) ParseCommand() (base, extra []string, err error)

ParseCommand returns a service command as two stream of strings. The base command is returned as a stream and the default arguments in [ ... ] group is returned as another stream.

type ServiceAction

type ServiceAction string

const (
	// Actions allowed in all contexts
	ActionUnset    ServiceAction = ""
	ActionRestart  ServiceAction = "restart"
	ActionShutdown ServiceAction = "shutdown"
	ActionIgnore   ServiceAction = "ignore"

	// Actions only allowed in specific contexts
	ActionFailureShutdown ServiceAction = "failure-shutdown"
	ActionSuccessShutdown ServiceAction = "success-shutdown"
)

type ServiceStartup

type ServiceStartup string

const (
	StartupUnknown  ServiceStartup = ""
	StartupEnabled  ServiceStartup = "enabled"
	StartupDisabled ServiceStartup = "disabled"
)

type TCPCheck

type TCPCheck struct {
	Port int    `yaml:"port,omitempty"`
	Host string `yaml:"host,omitempty"`
}

TCPCheck holds the configuration for an HTTP health check.

func (*TCPCheck) Copy

func (c *TCPCheck) Copy() *TCPCheck

Copy returns a deep copy of the TCP check configuration.

func (*TCPCheck) Merge

func (c *TCPCheck) Merge(other *TCPCheck)

Merge merges the fields set in other into c.