runtime

Documentation

Overview

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

Index

• Variables
• func IsRebootError(err error) bool
• type ActorIDCtxKey
• type Board
• type BoardInstallOptions
• type ClusterState
• type Controller
• 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 NewEvent(payload proto.Message, actorID string) Event
  • func (event *Event) ToMachineEvent() (*machine.Event, error)
• type EventFatalSequencerError
• type EventInfo
• type EventSequenceStart
• type EventStream
• type LockOption
  • func WithTakeover() LockOption
• type LockOptions
  • func DefaultControllerOptions() LockOptions
• 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 Meta
• type Mode
  • func ParseMode(s string) (mod Mode, err error)
  • func (m Mode) InContainer() bool
  • 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) CanTakeOver(running Sequence) bool
  • func (s Sequence) String() string
• type Sequencer
• type State
• type TaskExecutionFunc
• type TaskSetupFunc
• type V1Alpha2Controller
• type V1Alpha2State
• type WatchFunc
• type WatchOptionFunc
  • func WithActorID(actorID string) 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 = errors.New("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 ActorIDCtxKey

type ActorIDCtxKey struct{}

ActorIDCtxKey is the context key used for event actor id.

type Board

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

Board defines the requirements for a SBC.

type BoardInstallOptions

type BoardInstallOptions struct {
	InstallDisk     string
	MountPrefix     string
	DTBPath         string
	UBootPath       string
	RPiFirmwarePath string
	Printf          func(string, ...any)
}

BoardInstallOptions are the board specific options for installation of various boot assets.

type ClusterState

type ClusterState any

ClusterState defines the cluster state.

type Controller

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

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

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
	ActorID string
}

Event is what is sent on the wire.

func NewEvent

func NewEvent(payload proto.Message, actorID string) Event

NewEvent creates a new event with the provided payload and actor ID.

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 LockOption

type LockOption func(o *LockOptions) error

LockOption represents an option setter.

func WithTakeover

func WithTakeover() LockOption

WithTakeover sets the take option to true.

type LockOptions

type LockOptions struct {
	Takeover bool
}

LockOptions represents the options for a controller.

func DefaultControllerOptions

func DefaultControllerOptions() LockOptions

DefaultControllerOptions returns the default controller options.

type LogEvent

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

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

	// RegisteredLogs returns a list of registered logs containers.
	RegisteredLogs() []string
}

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 {
	Installed() bool
	IsInstallStaged() bool
	StagedInstallImageRef() string
	StagedInstallOptions() []byte
	KexecPrepared(bool)
	IsKexecPrepared() bool
	DBus() DBusState
	Meta() Meta
}

MachineState defines the machined state.

type Meta

type Meta interface {
	ReadTag(t uint8) (val string, ok bool)
	ReadTagBytes(t uint8) (val []byte, ok bool)
	SetTag(ctx context.Context, t uint8, val string) (bool, error)
	SetTagBytes(ctx context.Context, t uint8, val []byte) (bool, error)
	DeleteTag(ctx context.Context, t uint8) (bool, error)
	Reload(ctx context.Context) error
	Flush() error
}

Meta defines the access to META partition.

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) InContainer

func (m Mode) InContainer() bool

InContainer implements config.RuntimeMode.

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
	// MetaKV is META partition.
	MetaKV
)

type PartitionOptions

type PartitionOptions struct {
	PartitionsOffset uint64
}

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

type PartitionTarget

type PartitionTarget interface {
	Wipe(context.Context, func(string, ...any)) error
	GetLabel() string
}

PartitionTarget provides interface to the disk partition.

type Phase

type Phase struct {
	Name      string
	Tasks     []TaskSetupFunc
	CheckFunc func() bool
}

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, state.State) ([]byte, error)

	// KernelArgs returns additional kernel arguments which should be injected for the kernel boot.
	KernelArgs(arch string) 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, state.State, 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 []netip.Addr `yaml:"externalIPs"`

	Probes []network.ProbeSpecSpec `yaml:"probes,omitempty"`

	Metadata *runtime.PlatformMetadataSpec `yaml:"metadata,omitempty"`
}

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(context.Context, 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
	GetMode() machine.ResetRequest_WipeMode
	GetUserDisksToWipe() []string
	GetSystemDiskTargets() []PartitionTarget
}

ResetOptions are parameters to Reset sequence.

type Runtime

type Runtime interface {
	Config() config.Config
	ConfigContainer() config.Container
	RollbackToConfigAfter(time.Duration) error
	CancelConfigRollbackTimeout()
	SetConfig(config.Provider) error
	CanApplyImmediate(config.Provider) error
	State() State
	Events() EventStream
	Logging() LoggingManager
	NodeName() (string, error)
	IsBootstrapAllowed() bool
	GetSystemInformation(ctx context.Context) (*hardware.SystemInformation, error)
}

Runtime defines the runtime parameters.

type Sequence

type Sequence int

Sequence represents a sequence type.

const (
	// SequenceNoop is the noop sequence.
	SequenceNoop Sequence = iota
	// SequenceBoot is the boot sequence.
	SequenceBoot
	// 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
	// SequenceMaintenanceUpgrade is the upgrade sequence in maintenance mode.
	SequenceMaintenanceUpgrade
	// SequenceReset is the reset sequence.
	SequenceReset
	// SequenceReboot is the reboot sequence.
	SequenceReboot
)

func ParseSequence

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

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

func (Sequence) CanTakeOver

func (s Sequence) CanTakeOver(running Sequence) bool

CanTakeOver defines sequences priority.

| what is running (columns) what is requested (rows) | boot | reboot | reset | upgrade | |----------------------------------------------------|------|--------|-------|---------| | reboot | Y | Y | Y | N | | reset | Y | N | N | N | | upgrade | Y | N | N | N |.

func (Sequence) String

func (s Sequence) String() string

String returns the string representation of a `Sequence`.

type Sequencer

type Sequencer interface {
	Boot(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
	MaintenanceUpgrade(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 any) (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(configcore.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 WithActorID

func WithActorID(actorID string) WatchOptionFunc

WithActorID sets up Watcher to return events filtered by given actor id.

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
	// ActorID to ID of the actor to filter events by.
	ActorID string
}

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.