plan

package
v1.30.1 Latest Latest
Warning

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

 Go to latest Published: Apr 16, 2026 License: GPL-3.0 Imports: 16 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

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"

func RegisterSectionExtension added in v1.17.0 

func RegisterSectionExtension(field string, ext SectionExtension)

RegisterSectionExtension adds a plan schema extension. All registrations must be done before the plan library is used. The order in which extensions are registered determines the order in which the sections are marshalled. Extension sections are marshalled after the built-in sections.

func SectionDecode added in v1.20.0 

func SectionDecode(data *yaml.Node, v any) error

func UnregisterSectionExtension added in v1.17.0 

func UnregisterSectionExtension(field string)

UnregisterSectionExtension removes a plan schema extension. This is only intended for use by tests during cleanup.

Types

type Check 

type Check struct {
	// Basic details
	Name     string       `yaml:"-"`
	Override Override     `yaml:"override,omitempty"`
	Level    CheckLevel   `yaml:"level,omitempty"`
	Startup  CheckStartup `yaml:"startup,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 CheckStartup added in v1.19.0 

type CheckStartup string

CheckStartup defines the different startup modes for a check. 

const (
	CheckStartupUnknown  CheckStartup = ""
	CheckStartupEnabled  CheckStartup = "enabled"
	CheckStartupDisabled CheckStartup = "disabled"
)

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 ImmutableSection added in v1.29.0 

type ImmutableSection interface {
	Section

	// Immutable marks the section as immutable. It must implement no behavior.
	Immutable()

	// Equal reports whether this section is equal to other.
	Equal(other Section) bool
}

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"`

	Sections map[string]Section `yaml:",inline"`
}

Layer represents an unmarshalled YAML layer configuration file. Layer files are maintained as part of the Plan, ordered by their respective order number. Each layer configuration also has a unique label, used for locating and updating a specific layer configuration.

Pebble supports a two-level layer configuration directory structure. In the root layers directory, both layer files and layer sub-directories are allowed. Within a sub-directory, only layer files are allowed.

Please see ReadLayersDir for more details.

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(layersDir string) ([]*Layer, error)

ReadLayersDir loads the YAML layer files from the first two directory levels starting at layersDir in the order as specified by the order directory and file order prefixes. The directory and file suffixes are dropped in the returned labels. 

| File (inside layersDir)    | Order           | Label   |
| -------------------------- | --------------- | ------- |
| 001-foo.yaml               | 001-000 => 1000 | foo     |
| 002-bar.d/001-aaa.yaml     | 002-001 => 2001 | bar/aaa |
| 002-bar.d/002-bbb.yaml     | 002-002 => 2002 | bar/bbb |
| 003-baz.yaml               | 003-000 => 3000 | baz     |

func (*Layer) Validate added in v1.7.3 

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"
	OpenTelemetryTarget LogTargetType = "opentelemetry"
	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() (any, 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() (any, 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"`

	Sections map[string]Section `yaml:",inline"`
}

func NewPlan added in v1.20.0 

func NewPlan() *Plan

NewPlan creates an empty plan which includes empty registered extension fields. In the case of no plan layers, this ensures that plan callback handlers always get a valid extension backing type to access.

func ReadDir 

func ReadDir(layersDir string, base *Plan) (*Plan, error)

ReadDir reads the configuration layers from layersDir, and returns the resulting Plan. If layersDir doesn't exist, it returns a valid Plan with no layers. If base is not nil, layers read from the given layersDir will be stacked on top of the given base plan.

func (*Plan) MarshalYAML added in v1.17.0 

func (p *Plan) MarshalYAML() (any, error)

MarshalYAML implements an override for top level omitempty tags handling. This is required since Sections are based on an inlined map, for which omitempty and inline together is not currently supported.

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 added in v1.7.3 

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 Section added in v1.17.0 

type Section interface {
	// Validate checks whether the section is valid, returning an error if not.
	Validate() error

	// IsZero reports whether the section is empty.
	IsZero() bool
}

type SectionExtension added in v1.17.0 

type SectionExtension interface {
	// ParseSection returns a newly allocated concrete type containing the
	// unmarshalled section content.
	ParseSection(data yaml.Node) (Section, error)

	// CombineSections returns a newly allocated concrete type containing the
	// result of combining the supplied sections in order.
	CombineSections(sections ...Section) (Section, error)

	// ValidatePlan takes the complete plan as input, and allows the
	// extension to validate the plan. This can be used for cross section
	// dependency validation.
	ValidatePlan(plan *Plan) error
}

SectionExtension allows the plan layer schema to be extended without adding centralised schema knowledge to the plan library.

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
	Workload    string            `yaml:"workload,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"`

	// 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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.