runtime

package
v1.8.0 Latest Latest
Warning

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

Go to latest
Published: Sep 23, 2024 License: MPL-2.0 Imports: 22 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 = 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 added in v1.6.0

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 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) InContainer added in v1.7.0

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.

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 emergency provides values to handle emergency (panic/unrecoverable error) handling for machined.
Package emergency provides values to handle emergency (panic/unrecoverable error) handling for machined.
Package logging provides implementations of runtime.LoggingManager.
Package logging provides implementations of runtime.LoggingManager.
Package v1alpha1 implements a `Runtime`.
Package v1alpha1 implements a `Runtime`.
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/akamai
Package akamai contains the Akamai implementation of the [platform.Platform].
Package akamai contains the Akamai implementation of the [platform.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/cloudstack
Package cloudstack contains the Cloudstack platform implementation.
Package cloudstack contains the Cloudstack platform implementation.
platform/container
Package container contains the Container implementation of the [platform.Platform].
Package container contains the Container implementation of the [platform.Platform].
platform/container/internal/files
Package files provides internal methods to container platform to read files.
Package files provides internal methods to container platform to read files.
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/oauth2
Package oauth2 implements OAuth2 Device Flow to authenticate machine config download.
Package oauth2 implements OAuth2 Device Flow to authenticate machine config download.
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/opennebula
Package opennebula provides the OpenNebula platform implementation.
Package opennebula provides the OpenNebula 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