runtime

package
v1.6.0-alpha.1 Latest Latest
Warning

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

 Go to latest Published: Oct 17, 2023 License: MPL-2.0 Imports: 24 Imported by: 0

Documentation

Overview

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

Index

Constants

This section is empty.

Variables

View Source 
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")
)
View Source 
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 ActorIDCtxKey 

type ActorIDCtxKey struct{}

ActorIDCtxKey is the context key used for event actor id.

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{}, ...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]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
	Meta() Meta
}

MachineState defines the machined state.

type Meta added in v1.4.0 

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) 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 {
	fmt.Stringer
	Format(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() 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.

Source Files

View all Source files

Directories

Path Synopsis
Package disk contains abstract utility function to filter disks in MachineState.Disk call.
 Package disk contains abstract utility function to filter disks in MachineState.Disk call.
Package logging provides implementations of runtime.LoggingManager.
 Package logging provides implementations of runtime.LoggingManager.
Package v1alpha1 implements a `Runtime`.
 Package v1alpha1 implements a `Runtime`.
acpi
board
Package board provides the function to discover the current board.
 Package board provides the function to discover the current board.
board/bananapi_m64
Package bananapim64 provides the Banana Pi M64 board implementation.
 Package bananapim64 provides the Banana Pi M64 board implementation.
board/jetson_nano
Package jetsonnano provides the Jetson Nano board implementation.
 Package jetsonnano provides the Jetson Nano board implementation.
board/libretech_all_h3_cc_h5
Package libretechallh3cch5 provides the LibretechAllH3CCH5 board implementation.
 Package libretechallh3cch5 provides the LibretechAllH3CCH5 board implementation.
board/nanopi_r4s
Package nanopir4s provides the Nano Pi R4S board implementation.
 Package nanopir4s provides the Nano Pi R4S board implementation.
board/pine64
Package pine64 provides the Pine64 board implementation.
 Package pine64 provides the Pine64 board implementation.
board/rock64
Package rock64 provides the Pine64 Rock64 board implementation.
 Package rock64 provides the Pine64 Rock64 board implementation.
board/rockpi4
Package rockpi4 provides the Radxa rock pi implementation.
 Package rockpi4 provides the Radxa rock pi implementation.
board/rockpi4c
Package rockpi4c provides the Radxa rock pi implementation.
 Package rockpi4c provides the Radxa rock pi implementation.
board/rpi_generic
Package rpigeneric provides the Raspberry Pi Compute Module 4 implementation.
 Package rpigeneric provides the Raspberry Pi Compute Module 4 implementation.
bootloader
Package bootloader provides bootloader implementation.
 Package bootloader provides bootloader implementation.
bootloader/grub
Package grub provides the interface to the GRUB bootloader: config management, installation, etc.
 Package grub provides the interface to the GRUB bootloader: config management, installation, etc.
bootloader/mount
Package mount provides bootloader mount operations.
 Package mount provides bootloader mount operations.
bootloader/options
Package options provides bootloader options.
 Package options provides bootloader options.
bootloader/sdboot
Package sdboot provides the interface to the Systemd-Boot bootloader: config management, installation, etc.
 Package sdboot provides the interface to the Systemd-Boot bootloader: config management, installation, etc.
platform
Package platform provides functions to get the runtime.Platform.
 Package platform provides functions to get the runtime.Platform.
platform/aws
Package aws contains the AWS implementation of the [platform.Platform].
 Package aws contains the AWS implementation of the [platform.Platform].
platform/azure
Package azure contains the Azure implementation of the [platform.Platform].
 Package azure contains the Azure implementation of the [platform.Platform].
platform/container
Package container contains the Container implementation of the [platform.Platform].
 Package container contains the Container implementation of the [platform.Platform].
platform/digitalocean
Package digitalocean contains the Digital Ocean implementation of the [platform.Platform].
 Package digitalocean contains the Digital Ocean implementation of the [platform.Platform].
platform/equinixmetal
Package equinixmetal contains the Equinix Metal implementation of the [platform.Platform].
 Package equinixmetal contains the Equinix Metal implementation of the [platform.Platform].
platform/errors
Package errors contains errors used by the platform package.
 Package errors contains errors used by the platform package.
platform/exoscale
Package exoscale contains the Exoscale platform implementation.
 Package exoscale contains the Exoscale platform implementation.
platform/gcp
Package gcp contains the GCP implementation of the [platform.Platform].
 Package gcp contains the GCP implementation of the [platform.Platform].
platform/hcloud
Package hcloud contains the Hcloud implementation of the [platform.Platform].
 Package hcloud contains the Hcloud implementation of the [platform.Platform].
platform/internal/address
Package address provides utility functions for address parsing.
 Package address provides utility functions for address parsing.
platform/internal/netutils
Package netutils provides network-related helpers for platform implementation.
 Package netutils provides network-related helpers for platform implementation.
platform/metal
Package metal contains the metal implementation of the [platform.Platform].
 Package metal contains the metal implementation of the [platform.Platform].
platform/metal/url
Package url handles expansion of the download URL for the config.
 Package url handles expansion of the download URL for the config.
platform/nocloud
Package nocloud provides the NoCloud platform implementation.
 Package nocloud provides the NoCloud platform implementation.
platform/openstack
Package openstack provides the Openstack platform implementation.
 Package openstack provides the Openstack platform implementation.
platform/oracle
Package oracle provides the Oracle platform implementation.
 Package oracle provides the Oracle platform implementation.
platform/scaleway
Package scaleway provides the Scaleway platform implementation.
 Package scaleway provides the Scaleway platform implementation.
platform/upcloud
Package upcloud provides the UpCloud platform implementation.
 Package upcloud provides the UpCloud platform implementation.
platform/vmware
Package vmware provides the VMware platform implementation.
 Package vmware provides the VMware platform implementation.
platform/vultr
Package vultr provides the Vultr platform implementation.
 Package vultr provides the Vultr platform implementation.
Package v1alpha2 provides runtime implementation based on os-runtime.
 Package v1alpha2 provides runtime implementation based on os-runtime.

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.