instance

package
v0.0.0-...-01754d1 Latest Latest
Warning

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

 Go to latest Published: Apr 18, 2026 License: AGPL-3.0 Imports: 47 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ConsoleTypeConsole = "console"
	ConsoleTypeVGA     = "vga"
)

Possible values for the protocol argument of the Instance.Console() method.

View Source 
const HookStart = "onstart"

HookStart hook used when instance has started.

View Source 
const HookStartHost = "onstarthost"

HookStartHost hook used when instance is fully ready to be started.

View Source 
const HookStop = "onstop"

HookStop hook used when instance has stopped.

View Source 
const HookStopNS = "onstopns"

HookStopNS hook used when instance has stopped but before namespaces have been destroyed.

View Source 
const PowerStateRunning = "RUNNING"

PowerStateRunning represents the power state stored when an instance is running.

View Source 
const PowerStateStopped = "STOPPED"

PowerStateStopped represents the power state stored when an instance is stopped.

Variables

View Source 
var Create func(ctx context.Context, s *state.State, args db.InstanceArgs, p api.Project) (Instance, revert.Hook, error)

Create is linked from instance/drivers.create to allow difference instance types to be created. Returns a revert fail function that can be used to undo this function if a subsequent step fails.

View Source 
var ErrNotImplemented = errors.New("Not implemented")

ErrNotImplemented is the "Not implemented" error.

View Source 
var Load func(s *state.State, args db.InstanceArgs, p api.Project) (Instance, error)

Load is linked from instance/drivers.load to allow different instance types to be loaded.

View Source 
var ValidDevices func(state *state.State, p api.Project, instanceType instancetype.Type, localDevices deviceConfig.Devices, expandedDevices deviceConfig.Devices) error

ValidDevices is linked from instance/drivers.validDevices to validate device config.

Functions

func AllowedUnprivilegedOnlyMap 

func AllowedUnprivilegedOnlyMap(rawIdmap string) error

AllowedUnprivilegedOnlyMap checks that root user is not mapped into instance.

func BackupLoadByName 

func BackupLoadByName(s *state.State, project, name string) (*backup.InstanceBackup, error)

BackupLoadByName load an instance backup from the database.

func DeviceNextInterfaceHWAddr 

func DeviceNextInterfaceHWAddr() (string, error)

DeviceNextInterfaceHWAddr generates a random MAC address.

func FilterFull 

func FilterFull(instances []*api.InstanceFull, clauses filter.ClauseSet) ([]*api.InstanceFull, error)

FilterFull returns a filtered list of full instances that match the given clauses.

func IsSameLogicalInstance 

func IsSameLogicalInstance(inst Instance, dbInst *db.InstanceArgs) bool

IsSameLogicalInstance returns true if the supplied Instance and db.Instance have the same project and name or if they have the same volatile.uuid values.

func LoadInstanceDatabaseObject 

func LoadInstanceDatabaseObject(ctx context.Context, tx *db.ClusterTx, project, name string) (*cluster.Instance, error)

LoadInstanceDatabaseObject loads a db.Instance object, accounting for snapshots.

func MoveTemporaryName 

func MoveTemporaryName(inst Instance) (string, error)

MoveTemporaryName returns a name derived from the instance's volatile.uuid, to use when moving an instance across pools or cluster members which can be used for the naming the temporary copy before deleting the original instance and renaming the copy to the original name. If volatile.uuid is not set, a new UUID is generated and stored in the instance's config.

func NextSnapshotName 

func NextSnapshotName(s *state.State, inst Instance, defaultPattern string) (string, error)

NextSnapshotName finds the next snapshot for an instance.

func ResolveImage 

func ResolveImage(ctx context.Context, tx *db.ClusterTx, projectName string, source api.InstanceSource) (string, error)

ResolveImage takes an instance source and returns a hash suitable for instance creation or download.

func SnapshotProtobufToInstanceArgs 

func SnapshotProtobufToInstanceArgs(s *state.State, inst Instance, snap *migration.Snapshot) (*db.InstanceArgs, error)

SnapshotProtobufToInstanceArgs converts a migration snapshot record to DB instance record format.

func SnapshotToProtobuf 

func SnapshotToProtobuf(snap *api.InstanceSnapshot) *migration.Snapshot

SnapshotToProtobuf converts a snapshot record to a migration snapshot record.

func SuitableArchitectures 

func SuitableArchitectures(ctx context.Context, s *state.State, tx *db.ClusterTx, projectName string, sourceInst *cluster.Instance, sourceImageRef string, req api.InstancesPost) ([]int, error)

SuitableArchitectures returns a slice of architecture ids based on an instance create request.

An empty list indicates that the request may be handled by any architecture. A nil list indicates that we can't tell at this stage, typically for private images.

func ValidConfig 

func ValidConfig(sysOS *sys.OS, config map[string]string, expanded bool, instanceType instancetype.Type) error

ValidConfig validates an instance's config.

Types

type Cmd 

type Cmd interface {
	Wait() (int, error)
	PID() int
	Signal(s unix.Signal) error
	WindowResize(fd, winchWidth, winchHeight int) error
}

Cmd represents a local or remote command being run.

type ConfigReader 

type ConfigReader interface {
	Project() api.Project
	Type() instancetype.Type
	Architecture() int
	ID() int

	ExpandedConfig() map[string]string
	ExpandedDevices() deviceConfig.Devices
	LocalConfig() map[string]string
	LocalDevices() deviceConfig.Devices
}

ConfigReader is used to read instance config.

type Container 

type Container interface {
	Instance

	CurrentIdmap() (*idmap.IdmapSet, error)
	DiskIdmap() (*idmap.IdmapSet, error)
	NextIdmap() (*idmap.IdmapSet, error)
	ConsoleLog(ctx context.Context, opts liblxc.ConsoleLogOptions) (string, error)
	InsertSeccompUnixDevice(prefix string, m deviceConfig.Device, pid int) error
	DevptsFd() (*os.File, error)
	FileSFTPNoLock() (*sftp.Client, error)
	IdmappedStorage(path string, fstype string) idmap.IdmapStorageType
}

Container interface is for container specific functions.

type ConversionArgs 

type ConversionArgs struct {
	FilesystemConn func(ctx context.Context) (io.ReadWriteCloser, error)
	Disconnect     func()
}

ConversionArgs represent arguments for instance conversion send and receive.

type ConversionReceiveArgs 

type ConversionReceiveArgs struct {
	ConversionArgs
	SourceDiskSize    int64 // Size of the disk in bytes.
	ConversionOptions []string
}

ConversionReceiveArgs represent arguments for instance conversion receive.

type CriuMigrationArgs 

type CriuMigrationArgs struct {
	Cmd          uint
	StateDir     string
	Function     string
	Stop         bool
	ActionScript bool
	DumpDir      string
	PreDumpDir   string
	Features     liblxc.CriuFeatures
	Op           *operationlock.InstanceOperation
}

CriuMigrationArgs arguments for CRIU migration.

type Info 

type Info struct {
	Name     string            // Name of an instance driver, e.g. "lxc"
	Version  string            // Version number of a loaded instance driver
	Error    error             // Whether there is an operational impediment.
	Type     instancetype.Type // Instance type that the driver provides support for.
	Features map[string]any    // Map of supported features.
}

Info represents information about an instance driver.

type Instance 

type Instance interface {
	ConfigReader

	// Instance actions.
	Freeze(ctx context.Context) error
	Shutdown(ctx context.Context, timeout time.Duration) error
	Start(ctx context.Context, progressReporter ioprogress.ProgressReporter, stateful bool) error
	Stop(ctx context.Context, stateful bool) error
	Restart(ctx context.Context, timeout time.Duration, progressReporter ioprogress.ProgressReporter) error
	Rebuild(ctx context.Context, img *api.Image, op *operations.Operation) error
	Unfreeze(ctx context.Context) error
	RegisterDevices()

	Info() Info
	IsPrivileged() bool

	// Snapshots & migration & backups.
	Restore(ctx context.Context, source Instance, stateful bool, diskVolumesMode string, progressReporter ioprogress.ProgressReporter) error
	Snapshot(ctx context.Context, name string, expiry *time.Time, stateful bool, diskVolumesMode string, progressReporter ioprogress.ProgressReporter) error
	Snapshots() ([]Instance, error)
	Backups() ([]backup.InstanceBackup, error)
	UpdateBackupFile() error

	// Config handling.
	Rename(ctx context.Context, newName string, applyTemplateTrigger bool) error
	Update(ctx context.Context, newConfig db.InstanceArgs, actionType UpdateAction) error

	Delete(ctx context.Context, force bool, diskVolumesMode string, progressReporter ioprogress.ProgressReporter) error
	Export(w io.Writer, properties map[string]string, expiration time.Time, tracker *ioprogress.ProgressTracker) (api.ImageMetadata, error)

	// Live configuration.
	CGroup() (*cgroup.CGroup, error)
	VolatileSet(changes map[string]string) error
	SetAffinity(set []string) error

	// File handling.
	FileSFTPConn() (net.Conn, error)
	FileSFTP() (*sftp.Client, error)

	// Console - Allocate and run a console tty or a spice Unix socket.
	Console(ctx context.Context, protocol string) (*os.File, chan error, error)
	Exec(ctx context.Context, req api.InstanceExecPost, stdin *os.File, stdout *os.File, stderr *os.File) (Cmd, error)

	// Status
	Render(options ...func(response any) error) (any, any, error)
	RenderFull(hostInterfaces []net.Interface, opts ...StateRenderOptions) (*api.InstanceFull, any, error)
	RenderState(hostInterfaces []net.Interface, opts ...StateRenderOptions) (*api.InstanceState, error)
	IsRunning() bool
	IsFrozen() bool
	IsEphemeral() bool
	IsSnapshot() bool
	IsStateful() bool
	LockExclusive() (*operationlock.InstanceOperation, error)

	// Hooks.
	DeviceEventHandler(*deviceConfig.RunConfig) error
	OnHook(hookName string, args map[string]string) error

	// Properties.
	Location() string
	Name() string
	CloudInitID() string
	Description() string
	CreationDate() time.Time
	LastUsedDate() time.Time

	Profiles() []api.Profile
	InitPID() int
	State() string
	ExpiryDate() time.Time
	FillNetworkDevice(name string, m deviceConfig.Device) (deviceConfig.Device, error)

	// Paths.
	Path() string
	ExecOutputPath() string
	RootfsPath() string
	TemplatesPath() string
	StatePath() string
	LogFilePath() string
	ConsoleBufferLogPath() string
	LogPath() string
	DevicesPath() string

	// Storage.
	StoragePool() (string, error)

	// Migration.
	CanMigrate() (bool, bool)
	MigrateSend(ctx context.Context, args MigrateSendArgs, progressReporter ioprogress.ProgressReporter) error
	MigrateReceive(ctx context.Context, args MigrateReceiveArgs, progressReporter ioprogress.ProgressReporter) error

	// Conversion.
	ConversionReceive(args ConversionReceiveArgs, progressReporter ioprogress.ProgressReporter) error

	DeferTemplateApply(trigger TemplateTrigger) error

	Metrics(hostInterfaces []net.Interface) (*metrics.MetricSet, error)
}

Instance interface.

func CreateInternal 

func CreateInternal(ctx context.Context, s *state.State, args db.InstanceArgs, clearLogDir bool) (Instance, *operationlock.InstanceOperation, revert.Hook, error)

CreateInternal creates an instance record and storage volume record in the database and sets up devices. Accepts a reverter that revert steps this function does will be added to. It is up to the caller to call the revert's Fail() or Success() function as needed. Returns the created instance, along with a "create" operation lock that needs to be marked as Done once the instance is fully completed, and a revert fail function that can be used to undo this function if a subsequent step fails.

func LoadByID 

func LoadByID(s *state.State, id int) (Instance, error)

LoadByID loads an instance by ID.

func LoadByProjectAndName 

func LoadByProjectAndName(s *state.State, projectName string, instanceName string) (Instance, error)

LoadByProjectAndName loads an instance by project and name.

func LoadFromBackup 

func LoadFromBackup(s *state.State, projectName string, instancePath string) (Instance, error)

LoadFromBackup loads from a mounted instance's backup file without needing the database. Project config is not populated (as not in the backup file), however expanded config from backup file is applied to avoid needing to expand config by loading profiles from database.

func LoadNodeAll 

func LoadNodeAll(s *state.State, instanceType instancetype.Type) ([]Instance, error)

LoadNodeAll loads all instances on this server.

type MigrateArgs 

type MigrateArgs struct {
	ControlSend           func(m proto.Message) error
	ControlReceive        func(m proto.Message) error
	StateConn             func(ctx context.Context) (io.ReadWriteCloser, error)
	FilesystemConn        func(ctx context.Context) (io.ReadWriteCloser, error)
	Snapshots             bool
	Live                  bool
	Disconnect            func()
	ClusterMoveSourceName string // Will be empty if not a cluster move, otherwise indicates the source instance.
}

MigrateArgs represent arguments for instance migration send and receive.

type MigrateReceiveArgs 

type MigrateReceiveArgs struct {
	MigrateArgs

	InstanceOperation *operationlock.InstanceOperation
	Refresh           bool
}

MigrateReceiveArgs represent arguments for instance migration receive.

type MigrateSendArgs 

type MigrateSendArgs struct {
	MigrateArgs

	AllowInconsistent bool
}

MigrateSendArgs represent arguments for instance migration send.

type StateField 

type StateField string

StateField represents a specific state field that can be used with selective recursion. 

const (
	// StateFieldDisk represents the disk usage state field.
	StateFieldDisk StateField = "state.disk"
	// StateFieldNetwork represents the network state field.
	StateFieldNetwork StateField = "state.network"
)

type StateRenderOptions 

type StateRenderOptions struct {
	IncludeDisk    bool
	IncludeNetwork bool
}

StateRenderOptions controls which state fields should be included when rendering instance state.

func DefaultStateRenderOptions 

func DefaultStateRenderOptions() StateRenderOptions

DefaultStateRenderOptions returns the default state render options with all fields enabled.

func ParseRecursionFields 

func ParseRecursionFields(fields []string) (StateRenderOptions, error)

ParseRecursionFields converts a fields slice into StateRenderOptions.

A nil fields slice means no fields were specified (default behavior: all fields). An empty non-nil fields slice means no expensive fields should be fetched. A non-empty fields slice specifies exactly which fields to include.

type TemplateTrigger 

type TemplateTrigger string

TemplateTrigger trigger name. 

const TemplateTriggerCopy TemplateTrigger = "copy"

TemplateTriggerCopy for when an instance is copied. 

const TemplateTriggerCreate TemplateTrigger = "create"

TemplateTriggerCreate for when an instance is created. 

const TemplateTriggerRename TemplateTrigger = "rename"

TemplateTriggerRename for when an instance is renamed.

type UpdateAction 

type UpdateAction int

UpdateAction defines the trigger source for an instance update. 

const (
	// UpdateActionUser indicates an update directly requested by users.
	UpdateActionUser UpdateAction = iota

	// UpdateActionUserRefresh indicates an update requested by user requested refresh workflows.
	UpdateActionUserRefresh

	// UpdateActionInternal indicates an internal update not directly user requested.
	UpdateActionInternal
)

type VM 

type VM interface {
	Instance

	AgentCertificate() *x509.Certificate

	FirmwarePath() string

	// UEFI vars handling.
	UEFIVars() (*api.InstanceUEFIVars, error)
	UEFIVarsUpdate(newUEFIVarsSet api.InstanceUEFIVars) error
}

VM interface is for VM specific functions.

Source Files

View all Source files

Directories

Path Synopsis
edk2
qmp
uefi

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.