runtime

Documentation

Overview

Package runtime defines interfaces for accessing runtime specific settings, and state.

Index

• Variables
• func IsRebootError(err error) bool
• type Board
• type ClusterState
• type Controller
• type ControllerOption
  • func WithForce() ControllerOption
  • func WithTakeover() ControllerOption
• type ControllerOptions
  • func DefaultControllerOptions() ControllerOptions
• type DBusState
• type DrainEvent
• type DrainSubscription
  • func (s *DrainSubscription) Cancel()
  • func (s *DrainSubscription) EventCh() <-chan DrainEvent
• type Drainer
  • func NewDrainer() *Drainer
  • func (d *Drainer) Drain(ctx context.Context) error
  • func (d *Drainer) Subscribe() *DrainSubscription
• type Event
  • func (event *Event) ToMachineEvent() (*machine.Event, error)
• type EventFatalSequencerError
• type EventInfo
• type EventSequenceStart
• type EventStream
• type LogEvent
• type LogHandler
• type LogOption
  • func WithFollow() LogOption
  • func WithTailLines(lines int) LogOption
• type LogOptions
• type LogSender
• type LoggingManager
• type Machine
• type MachineState
• type Mode
  • func ParseMode(s string) (mod Mode, err error)
  • func (m Mode) RequiresInstall() bool
  • func (m Mode) String() string
  • func (m Mode) Supports(feature ModeCapability) bool
• type ModeCapability
• type PartitionOptions
• type PartitionTarget
• type Phase
• type Platform
• type PlatformNetworkConfig
• type Publisher
• type RebootError
  • func (e RebootError) Error() string
• type ResetOptions
• type Runtime
• type Sequence
  • func ParseSequence(s string) (seq Sequence, err error)
  • func (s Sequence) String() string
• type Sequencer
• type State
• type TaskExecutionFunc
• type TaskSetupFunc
• type V1Alpha2Controller
• type V1Alpha2State
• type WatchFunc
• type WatchOptionFunc
  • func WithTailDuration(dur time.Duration) WatchOptionFunc
  • func WithTailEvents(number int) WatchOptionFunc
  • func WithTailID(id xid.ID) WatchOptionFunc
• type WatchOptions
• type Watcher

Variables

var (
	// ErrLocked indicates that the sequencer is currently locked, and processing
	// another sequence.
	ErrLocked = errors.New("locked")

	// ErrInvalidSequenceData indicates that the sequencer got data the wrong
	// data type for a sequence.
	ErrInvalidSequenceData = errors.New("invalid sequence data")

	// ErrUndefinedRuntime indicates that the sequencer's runtime is not defined.
	ErrUndefinedRuntime = errors.New("undefined runtime")
)

var ErrDontRetry = fmt.Errorf("don't retry")

ErrDontRetry indicates that log event should not be resent.

Functions

func IsRebootError

func IsRebootError(err error) bool

IsRebootError checks whether given error is RebootError.

Types

type Board

type Board interface {
	Name() string
	Install(string) error
	KernelArgs() procfs.Parameters
	PartitionOptions() *PartitionOptions
}

Board defines the requirements for a SBC.

type ClusterState

type ClusterState interface{}

ClusterState defines the cluster state.

type Controller

type Controller interface {
	Runtime() Runtime
	Sequencer() Sequencer
	Run(context.Context, Sequence, interface{}, ...ControllerOption) error
	V1Alpha2() V1Alpha2Controller
}

Controller represents the controller responsible for managing the execution of sequences.

type ControllerOption

type ControllerOption func(o *ControllerOptions) error

ControllerOption represents an option setter.

func WithForce

func WithForce() ControllerOption

WithForce sets the force option to true.

func WithTakeover

func WithTakeover() ControllerOption

WithTakeover sets the take option to true.

type ControllerOptions

type ControllerOptions struct {
	Force    bool
	Takeover bool
}

ControllerOptions represents the options for a controller.

func DefaultControllerOptions

func DefaultControllerOptions() ControllerOptions

DefaultControllerOptions returns the default controller options.

type DBusState

type DBusState interface {
	Start() error
	Stop() error
	WaitShutdown(ctx context.Context) error
}

DBusState defines the D-Bus logind mock.

type DrainEvent

type DrainEvent struct{}

DrainEvent is sent to the events channel when drainer starts the shutdown sequence.

type DrainSubscription

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

DrainSubscription keeps ingoing and outgoing events channels.

func (*DrainSubscription) Cancel

func (s *DrainSubscription) Cancel()

Cancel the subscription which triggers drain to shutdown.

func (*DrainSubscription) EventCh

func (s *DrainSubscription) EventCh() <-chan DrainEvent

EventCh returns drain events channel.

type Drainer

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

Drainer is used in controllers to ensure graceful shutdown.

func NewDrainer

func NewDrainer() *Drainer

NewDrainer creates new drainer.

func (*Drainer) Drain

func (d *Drainer) Drain(ctx context.Context) error

Drain initializes drain sequence waits for it to succeed until the context is canceled.

func (*Drainer) Subscribe

func (d *Drainer) Subscribe() *DrainSubscription

Subscribe should be called from a controller that needs graceful shutdown.

type Event

type Event struct {
	TypeURL string
	ID      xid.ID
	Payload proto.Message
}

Event is what is sent on the wire.

func (*Event) ToMachineEvent

func (event *Event) ToMachineEvent() (*machine.Event, error)

ToMachineEvent serializes Event as proto message machine.Event.

type EventFatalSequencerError

type EventFatalSequencerError struct {
	Error    error
	Sequence Sequence
}

EventFatalSequencerError represents a fatal sequencer error.

type EventInfo

type EventInfo struct {
	Event
	Backlog int
}

EventInfo unifies event and queue information for the WatchFunc.

type EventSequenceStart

type EventSequenceStart struct {
	Sequence Sequence
}

EventSequenceStart represents the sequence start event.

type EventStream

type EventStream interface {
	Watcher
	Publisher
}

EventStream defines the runtime event stream.

type LogEvent

type LogEvent struct {
	Msg    string
	Time   time.Time
	Level  zapcore.Level
	Fields map[string]interface{}
}

LogEvent represents a log message to be send.

type LogHandler

type LogHandler interface {
	Writer() (io.WriteCloser, error)
	Reader(opt ...LogOption) (io.ReadCloser, error)
}

LogHandler provides interface to access particular log source.

type LogOption

type LogOption func(*LogOptions) error

LogOption provides functional options for LogHandler.Reader.

func WithFollow

func WithFollow() LogOption

WithFollow enables follow mode for the logs.

func WithTailLines

func WithTailLines(lines int) LogOption

WithTailLines starts log reading from lines from the tail of the log.

type LogOptions

type LogOptions struct {
	Follow    bool
	TailLines *int
}

LogOptions for LogHandler.Reader.

type LogSender

type LogSender interface {
	// Send tries to send the log event once, exiting on success, error, or context cancelation.
	//
	// Returned error is nil on success, non-nil otherwise.
	// As a special case, Send can return (possibly wrapped) ErrDontRetry if the log event should not be resent
	// (if it is invalid, if it was sent partially, etc).
	//
	// Send should be thread-safe.
	Send(ctx context.Context, e *LogEvent) error

	// Close stops the sender gracefully if possible, or forcefully on context cancelation.
	//
	// Close should be thread-safe.
	Close(ctx context.Context) error
}

LogSender provides common interface for log senders.

type LoggingManager

type LoggingManager interface {
	// ServiceLog privides a log handler for a given service (that may not exist).
	ServiceLog(service string) LogHandler

	// SetSenders sets log senders for all derived log handlers
	// and returns the previous ones for closing.
	//
	// SetSenders should be thread-safe.
	SetSenders(senders []LogSender) []LogSender
}

LoggingManager provides unified interface to publish and consume logs.

type Machine

type Machine interface {
	State() MachineState
	Config() config.MachineConfig
}

Machine defines the runtime parameters.

type MachineState

type MachineState interface {
	Disk(options ...disk.Option) *probe.ProbedBlockDevice
	Close() error
	Installed() bool
	IsInstallStaged() bool
	StagedInstallImageRef() string
	StagedInstallOptions() []byte
	KexecPrepared(bool)
	IsKexecPrepared() bool
	DBus() DBusState
}

MachineState defines the machined state.

type Mode

type Mode int

Mode is a runtime mode.

const (
	// ModeCloud is the cloud runtime mode.
	ModeCloud Mode = iota
	// ModeContainer is the container runtime mode.
	ModeContainer
	// ModeMetal is the metal runtime mode.
	ModeMetal
)

func ParseMode

func ParseMode(s string) (mod Mode, err error)

ParseMode returns a `Mode` that matches the specified string.

func (Mode) RequiresInstall

func (m Mode) RequiresInstall() bool

RequiresInstall implements config.RuntimeMode.

func (Mode) String

func (m Mode) String() string

String returns the string representation of a Mode.

func (Mode) Supports

func (m Mode) Supports(feature ModeCapability) bool

Supports returns mode capability.

type ModeCapability

type ModeCapability uint64

ModeCapability describes mode capability flags.

const (
	// Reboot node reboot.
	Reboot ModeCapability = 1 << iota
	// Rollback node rollback.
	Rollback
	// Shutdown node shutdown.
	Shutdown
	// Upgrade node upgrade.
	Upgrade
)

type PartitionOptions

type PartitionOptions struct {
	PartitionsOffset uint64
}

PartitionOptions are the board specific options for customizing the partition table.

type PartitionTarget

type PartitionTarget interface {
	fmt.Stringer
	Format() error
	GetLabel() string
}

PartitionTarget provides interface to the disk partition.

type Phase

type Phase struct {
	Name  string
	Tasks []TaskSetupFunc
}

Phase represents a collection of tasks to be performed concurrently.

type Platform

type Platform interface {
	// Name returns platform name.
	Name() string

	// Mode returns platform mode (metal, cloud or container).
	Mode() Mode

	// Configuration fetches the machine configuration from platform-specific location.
	//
	// On cloud-like platform it is user-data in metadata service.
	// For metal platform that is either `talos.config=` URL or mounted ISO image.
	Configuration(context.Context) ([]byte, error)

	// KernelArgs returns additional kernel arguments which should be injected for the kernel boot.
	KernelArgs() procfs.Parameters

	// NetworkConfiguration fetches network configuration from the platform metadata.
	//
	// Controller will run this in function a separate goroutine, restarting it
	// on error. Platform is expected to deliver network configuration over the channel,
	// including updates to the configuration over time.
	NetworkConfiguration(context.Context, chan<- *PlatformNetworkConfig) error
}

Platform defines the requirements for a platform.

type PlatformNetworkConfig

type PlatformNetworkConfig struct {
	Addresses []network.AddressSpecSpec `yaml:"addresses"`
	Links     []network.LinkSpecSpec    `yaml:"links"`
	Routes    []network.RouteSpecSpec   `yaml:"routes"`

	Hostnames   []network.HostnameSpecSpec   `yaml:"hostnames"`
	Resolvers   []network.ResolverSpecSpec   `yaml:"resolvers"`
	TimeServers []network.TimeServerSpecSpec `yaml:"timeServers"`

	Operators []network.OperatorSpecSpec `yaml:"operators"`

	ExternalIPs []netaddr.IP `yaml:"externalIPs"`
}

PlatformNetworkConfig describes the network configuration produced by the platform.

This structure is marshaled to STATE partition to persist cached network configuration across reboots.

type Publisher

type Publisher interface {
	Publish(proto.Message)
}

Publisher defines a runtime event publisher.

type RebootError

type RebootError struct {
	Cmd int
}

RebootError encapsulates unix.Reboot() cmd argument.

func (RebootError) Error

func (e RebootError) Error() string

type ResetOptions

type ResetOptions interface {
	GetGraceful() bool
	GetReboot() bool
	GetSystemDiskTargets() []PartitionTarget
}

ResetOptions are parameters to Reset sequence.

type Runtime

type Runtime interface {
	Config() config.Provider
	LoadAndValidateConfig([]byte) (config.Provider, error)
	RollbackToConfigAfter([]byte, time.Duration) error
	CancelConfigRollbackTimeout()
	SetConfig(config.Provider) error
	CanApplyImmediate(config.Provider) error
	State() State
	Events() EventStream
	Logging() LoggingManager
	NodeName() (string, error)
	IsBootstrapAllowed() bool
}

Runtime defines the runtime parameters.

type Sequence

type Sequence int

Sequence represents a sequence type.

const (
	// SequenceBoot is the boot sequence.
	SequenceBoot Sequence = iota
	// SequenceBootstrap is the boot sequence.
	SequenceBootstrap
	// SequenceInitialize is the initialize sequence.
	SequenceInitialize
	// SequenceInstall is the install sequence.
	SequenceInstall
	// SequenceShutdown is the shutdown sequence.
	SequenceShutdown
	// SequenceUpgrade is the upgrade sequence.
	SequenceUpgrade
	// SequenceStageUpgrade is the stage upgrade sequence.
	SequenceStageUpgrade
	// SequenceReset is the reset sequence.
	SequenceReset
	// SequenceReboot is the reboot sequence.
	SequenceReboot
	// SequenceNoop is the noop sequence.
	SequenceNoop
)

func ParseSequence

func ParseSequence(s string) (seq Sequence, err error)

ParseSequence returns a `Sequence` that matches the specified string.

func (Sequence) String

func (s Sequence) String() string

String returns the string representation of a `Sequence`.

type Sequencer

type Sequencer interface {
	Boot(Runtime) []Phase
	Bootstrap(Runtime) []Phase
	Initialize(Runtime) []Phase
	Install(Runtime) []Phase
	Reboot(Runtime) []Phase
	Reset(Runtime, ResetOptions) []Phase
	Shutdown(Runtime, *machine.ShutdownRequest) []Phase
	StageUpgrade(Runtime, *machine.UpgradeRequest) []Phase
	Upgrade(Runtime, *machine.UpgradeRequest) []Phase
}

Sequencer describes the set of sequences required for the lifecycle management of the operating system.

type State

type State interface {
	Platform() Platform
	Machine() MachineState
	Cluster() ClusterState
	V1Alpha2() V1Alpha2State
}

State defines the state.

type TaskExecutionFunc

type TaskExecutionFunc func(context.Context, *log.Logger, Runtime) error

TaskExecutionFunc defines the function that a task will execute for a specific runtime mode.

type TaskSetupFunc

type TaskSetupFunc func(seq Sequence, data interface{}) (TaskExecutionFunc, string)

TaskSetupFunc defines the function that a task will execute for a specific runtime mode.

type V1Alpha2Controller

type V1Alpha2Controller interface {
	Run(context.Context, *Drainer) error
	DependencyGraph() (*controller.DependencyGraph, error)
}

V1Alpha2Controller provides glue into v2alpha1 controller runtime.

type V1Alpha2State

type V1Alpha2State interface {
	Resources() state.State

	NamespaceRegistry() *registry.NamespaceRegistry
	ResourceRegistry() *registry.ResourceRegistry

	SetConfig(config.Provider) error
}

V1Alpha2State defines the next generation (v2) interface binding into v1 runtime.

type WatchFunc

type WatchFunc func(<-chan EventInfo)

WatchFunc defines the watcher callback function.

type WatchOptionFunc

type WatchOptionFunc func(opts *WatchOptions) error

WatchOptionFunc defines the options for the watcher.

func WithTailDuration

func WithTailDuration(dur time.Duration) WatchOptionFunc

WithTailDuration sets up Watcher to return events with timestamp >= (now - tailDuration).

func WithTailEvents

func WithTailEvents(number int) WatchOptionFunc

WithTailEvents sets up Watcher to return specified number of past events.

If number is negative, all the available past events are returned.

func WithTailID

func WithTailID(id xid.ID) WatchOptionFunc

WithTailID sets up Watcher to return events with ID > TailID.

type WatchOptions

type WatchOptions struct {
	// Return that many past events.
	//
	// If TailEvents is negative, return all the events available.
	TailEvents int
	// Start at ID > specified.
	TailID xid.ID
	// Start at timestamp Now() - TailDuration.
	TailDuration time.Duration
}

WatchOptions defines options for the watch call.

Only one of TailEvents, TailID or TailDuration should be non-zero.

type Watcher

type Watcher interface {
	Watch(WatchFunc, ...WatchOptionFunc) error
}

Watcher defines a runtime event watcher.