models

package
v0.16.0 Latest Latest
Warning

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

 Go to latest Published: Oct 3, 2026 License: MPL-2.0 Imports: 7 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	PendingState  = "pending"
	CreatedState  = "created"
	FailedState   = "failed"
	DeletingState = "deleting"
)
View Source 
const (
	// UIDLength is the length of a microvm UID. UIDs are always generated by flintlock as ULIDs.
	UIDLength = 26

	// MaxSocketNameLength is the length of the longest per-microvm socket file name
	// ("cloudhypervisor.sock").
	MaxSocketNameLength = 20

	// SocketSuffixReserve is the headroom reserved for suffixes the VMMs append to socket paths.
	// Firecracker and Cloud Hypervisor listen on "<vsock path>_<port>" for guest initiated
	// connections, where port is a uint32 (up to 10 digits).
	SocketSuffixReserve = 11

	// MaxUnixSocketPathLength is the maximum usable length of a unix socket path on Linux
	// (sun_path is 108 bytes including the terminating NUL).
	MaxUnixSocketPathLength = 107
)

Variables

This section is empty.

Functions

func MaxSocketDirLength added in v0.15.2 

func MaxSocketDirLength() int

MaxSocketDirLength returns the maximum length of the socket directory that keeps every per-microvm socket path within MaxUnixSocketPathLength.

func SocketRoot added in v0.15.2 

func SocketRoot(socketDir string, id VMID) string

SocketRoot returns the directory that holds the unix sockets for a microvm. It's keyed only by the UID, so its length doesn't depend on the microvm's namespace or name.

Types

type CPUConfig added in v0.12.0 

type CPUConfig struct {
	// FeaturesToEnable is a list of optional CPU features to enable. Supported by all providers,
	// but the accepted values are provider specific (e.g. named features such as "amx" for
	// Cloud Hypervisor, or numeric KVM capability IDs for Firecracker). The "!" prefix is
	// reserved for KVMCapabilitiesToDisable and is not allowed here.
	FeaturesToEnable []string `json:"features_to_enable,omitempty" validate:"omitempty,dive,min=1,excludesall=!"`
	// KVMCapabilitiesToDisable is a list of KVM capability IDs to disable. Only supported by
	// providers that declare the KVMCapabilitiesDisableCapability (currently Firecracker only).
	KVMCapabilitiesToDisable []string `json:"kvm_capabilities_to_disable,omitempty" validate:"omitempty,dive,kvmCapability"` //nolint: lll // struct tag can't be split
}

CPUConfig represents CPU feature configuration for a microvm.

type Capabilities 

type Capabilities []Capability

Capabilities represents a list of capabilities.

func (Capabilities) Has 

func (cp Capabilities) Has(hasCap Capability) bool

Has is used to test if this set of capabilities has a specific capability.

type Capability 

type Capability string

Capabaility represents a capability of a provider. 

const (
	// MetadataServiceCapability is a capability that indicates the microvm provider
	// has a metadata service.
	MetadataServiceCapability Capability = "metadata-service"

	// AutoStartCapability is a capability of the microvm provider where the vm is automatically started
	// as part of the creation process. If a provider doesn't have this capability then its assumed the
	// microvm will be started via a call to the start implementation of the provider.
	AutoStartCapability Capability = "auto-start"

	// MacvtapCapability is a capability that indocates the microvm provider
	// has support for macvtap network interfaces.
	MacvtapCapability Capability = "macvtap"

	VirtioFSCapability Capability = "virtiofs"

	// VSockCapability indicates the microvm provider supports attaching a vsock device
	// (used by the guest-agent).
	VSockCapability Capability = "vsock"

	// KVMCapabilitiesDisableCapability indicates the microvm provider supports disabling
	// specific KVM capabilities via CPUConfig.KVMCapabilitiesToDisable.
	KVMCapabilitiesDisableCapability Capability = "kvm-capabilities-disable"
)

type ContainerImage 

type ContainerImage string

ContainerImage represents the address of a OCI image.

type ContainerVolumeSource 

type ContainerVolumeSource struct {
	// Image is the OCI image to use.
	Image ContainerImage `json:"image"`
}

ContainerDriveSource represents the details of a volume coming from a OCI image.

type Drive added in v0.16.0 

type Drive struct {
	// ID is the identifier of the drive given to the VMM.
	ID string
	// Role is what the drive is used for.
	Role DriveRole
	// VolumeID is the id of the volume the drive holds. It is empty for a
	// drive that holds no volume, such as the cloud-init drive.
	VolumeID string
	// GuestDevice is the name of the device inside the guest, for example vdb.
	GuestDevice string
	// ReadOnly is true when the drive is presented read-only.
	ReadOnly bool
	// Path is the location of the drive on the host. It is empty until the
	// volume has been mounted.
	Path string
}

Drive is a block device that a provider presents to a microvm.

type DriveRole added in v0.16.0 

type DriveRole string

DriveRole is what a drive presented to a microvm is used for. 

const (
	// DriveRoleRoot is the drive that holds the root volume.
	DriveRoleRoot DriveRole = "root"
	// DriveRoleCloudInit is the drive that holds the cloud-init data.
	DriveRoleCloudInit DriveRole = "cloud-init"
	// DriveRoleVolume is a drive that holds an additional volume.
	DriveRoleVolume DriveRole = "volume"
)

type Drives added in v0.16.0 

type Drives []Drive

Drives is a list of drives in the order the guest sees them.

func (Drives) GuestDeviceForVolume added in v0.16.0 

func (d Drives) GuestDeviceForVolume(volumeID string) (string, bool)

GuestDeviceForVolume returns the guest device name of the drive that holds an additional volume. It returns false when no drive holds the volume, which is the case for a volume that is not a block device.

type EventEnvelope 

type EventEnvelope struct {
	// ID is the unique identifier for the event.
	ID string `json:"id"`
	// Topic is the name of the topic the event originated from.
	Topic string `json:"topic"`
	// Event is the actual event payload.
	Event interface{} `json:"event"`
}

EventEnvelope represents an event envelope.

type IPAddressCIDR 

type IPAddressCIDR string

IPAddressCIDR represents a IPv4/IPv6 address in CIDR notation.

func (IPAddressCIDR) IP 

func (i IPAddressCIDR) IP() (string, error)

func (IPAddressCIDR) IsIPv4 

func (i IPAddressCIDR) IsIPv4() (bool, error)

type IfaceType 

type IfaceType string

IfaceType is a type representing the supported network interface types. 

const (
	// IfaceTypeTap is a TAP network interface.
	IfaceTypeTap IfaceType = "tap"
	// IfaceTypeMacvtap is a MACVTAP network interface.
	IfaceTypeMacvtap IfaceType = "macvtap"
	// IfaceTypeUnsupported is a type that represents an unsupported network interface type.
	IfaceTypeUnsupported IfaceType = "unsupported"
)

type ImageUse 

type ImageUse string

ImageUse is a type representing the how an image will be used. 

const (
	// ImageUseVolume represents the usage of af an image for a volume.
	ImageUseVolume ImageUse = "volume"
	// ImageUseKernel represents the usage of af an image for a kernel.
	ImageUseKernel ImageUse = "kernel"
	// ImageUseKernel represents the usage of af an image for a initial ramdisk.
	ImageUseInitrd ImageUse = "initrd"
)

type Initrd 

type Initrd struct {
	// Image is the container image to use for the initrd.
	Image ContainerImage `json:"image" validate:"imageURI"`
	// Filename is the name of the initrd filename in the container.
	Filename string `validate:"required,imageFilePath"`
}

type Kernel 

type Kernel struct {
	// Image is the container image to use for the kernel.
	Image ContainerImage `json:"image" validate:"required,imageURI"`
	// Filename is the name of the kernel filename in the container.
	Filename string `validate:"required,imageFilePath"`
	// CmdLine are the args to use for the kernel cmdline.
	CmdLine map[string]string `json:"cmdline,omitempty"`
	// AddNetworkConfig if set to true indicates that the network-config kernel argument should be generated.
	AddNetworkConfig bool `json:"add_network_config"`
}

Kernel is the specification of the kernel and its arguments.

type ListMicroVMQuery 

type ListMicroVMQuery map[string]string

ListMicroVMQuery is a key-value map to query microvms.

type MicroVM 

type MicroVM struct {
	// ID is the identifier for the microvm.
	ID VMID `json:"id"`
	// Version is the version for the microvm definition.
	Version int `json:"version"`
	// Spec is the specification of the microvm.
	Spec MicroVMSpec `json:"spec"`
	// Status is the runtime status of the microvm.
	Status MicroVMStatus `json:"status"`
}

MicroVM represents a microvm machine that is created via a provider.

type MicroVMSpec 

type MicroVMSpec struct {
	// Provider specifies the name of the microvm provider to use.
	Provider string `json:"provider"`
	// Kernel specifies the kernel and its argments to use.
	Kernel Kernel `json:"kernel" validate:"omitempty"`
	// Initrd is an optional initial ramdisk to use.
	Initrd *Initrd `json:"initrd,omitempty"`
	// VCPU specifies how many vcpu the machine will be allocated.
	VCPU int64 `json:"vcpu" validate:"required,gte=1,lte=64"`
	// MemoryInMb is the amount of memory in megabytes that the machine will be allocated.
	MemoryInMb int64 `json:"memory_inmb" validate:"required,gte=1024,lte=32768"`
	// NetworkInterfaces specifies the network interfaces attached to the machine.
	NetworkInterfaces []NetworkInterface `json:"network_interfaces" validate:"required,dive,required"`
	// RootVolume specified the root volume to be attached to the machine.
	RootVolume Volume `json:"root_volume" validate:"required,novirtiofs"`
	// AdditionalVolumes specifies the volumes to be attached to the machine.
	AdditionalVolumes Volumes `json:"additional_volumes" validate:"onlyOneVirtioFS,multipleVolSources,noReadOnlyVirtioFS"`
	// Metadata allows you to specify data to be added to the metadata service. The key is the name
	// of the metadata item and the value is the base64 encoded contents of the metadata.
	Metadata map[string]string `json:"metadata"`
	// AllowGuestAgent, when true, attaches a vsock device so the in-guest guest-agent
	// can communicate with the host.
	AllowGuestAgent bool `json:"allow_guest_agent"`
	// CPUConfig allows you to customise the CPU features presented to the guest. Support and
	// semantics vary by provider.
	CPUConfig *CPUConfig `json:"cpu_config,omitempty" validate:"omitempty"`
	// CreatedAt indicates the time the microvm was created at.
	CreatedAt int64 `json:"created_at" validate:"omitempty,datetimeInPast"`
	// UpdatedAt indicates the time the microvm was last updated.
	UpdatedAt int64 `json:"updated_at" validate:"omitempty,datetimeInPast"`
	// DeletedAt indicates the time the microvm was marked as deleted.
	DeletedAt int64 `json:"deleted_at" validate:"omitempty,datetimeInPast"`
}

MicroVMSpec represents the specification of a microvm machine.

type MicroVMState 

type MicroVMState string

This state represents the state of the entire Flintlock MVM. The state for the Firecracker MVM itself is represented in ports.MicroVMState.

type MicroVMStatus 

type MicroVMStatus struct {
	// State stores information about the last known state of the vm and the spec.
	State MicroVMState `json:"state"`
	// Volumes holds the status of the volumes.
	Volumes VolumeStatuses `json:"volumes"`
	// KernelMount holds the status of the kernel mount point.
	KernelMount *Mount `json:"kernel_mount"`
	// InitrdMount holds the status of the initrd mount point.
	InitrdMount *Mount `json:"initrd_mount"`
	// NetworkInterfaces holds the status of the network interfaces.
	NetworkInterfaces NetworkInterfaceStatuses `json:"network_interfaces"`
	// Retry is a counter about how many times we retried to reconcile.
	Retry int `json:"retry"`
	// NotBefore tells the system to do not reconcile until given timestamp.
	NotBefore int64 `json:"not_before" validate:"omitempty"`
	// VSockPath is the host unix-domain socket path for the guest-agent vsock device.
	// Empty unless the spec has AllowGuestAgent set.
	VSockPath string `json:"vsock_path"`
}

MicroVMStatus contains the runtime status of the microvm.

type Mount 

type Mount struct {
	// Type specifies the type of the mount (e.g. device or directory).
	Type MountType `json:"type"`
	// Source is the location of the mounted volume.
	Source string `json:"source"`
}

Mount represents a volume mount point.

type MountType 

type MountType string

MountType is a type representing the type of mount. 

const (
	// MountTypeDev represents a mount point that is a block device.
	MountTypeDev MountType = "dev"
	// MountTypeHostPath represents a mount point that is a directory on the host.
	MountTypeHostPath MountType = "hostpath"
)

type NetworkInterface 

type NetworkInterface struct {
	// GuestDeviceName is the name of the network interface to create in the microvm.
	GuestDeviceName string `json:"guest_device_name" validate:"required,excludesall=/@,guestDeviceName"`
	// AllowMetadataRequests indicates that this interface can be used for metadata requests.
	//
	// NOTE: This field is not exposed via the gRPC API, it is automatically
	// populated when converting from the API model to this internal model.
	AllowMetadataRequests bool `json:"allow_mmds,omitempty"`
	// GuestMAC allows the specifying of a specifi MAC address to use for the interface. If
	// not supplied a autogenerated MAC address will be used.
	GuestMAC string `json:"guest_mac,omitempty" validate:"omitempty,mac"`
	// Type is the type of host network interface type to create to use by the guest.
	Type IfaceType `json:"type" validate:"oneof=tap macvtap unsupported"`
	// StaticAddress is an optional static IP address to assign to this interface.
	// If not supplied then DHCP will be used.
	StaticAddress *StaticAddress `json:"staticAddrss,omitempty"`
	// BridgeName is the name of the Linux bridge to attach the TAP device to.
	BridgeName string `json:"branch_name,omitempty"`
}

NetworkInterface represents a network interface for the microvm.

type NetworkInterfaceStatus 

type NetworkInterfaceStatus struct {
	// HostDeviceName is the name of the network interface used from the host. This will be
	// a tuntap or macvtap interface.
	HostDeviceName string `json:"host_device_name"`
	// Index is the index of the network interface on the host.
	Index int `json:"index"`
	// MACAddress is the MAC address of the host interface.
	MACAddress string `json:"mac_address"`
}

type NetworkInterfaceStatuses 

type NetworkInterfaceStatuses map[string]*NetworkInterfaceStatus

NetworkInterfaceStatuses is a collection of network interfaces.

type StaticAddress 

type StaticAddress struct {
	// Address is the static IP address (IPv4 or IPv6) to assign to this interface.
	// Must be CIDR notation.
	Address IPAddressCIDR `json:"address" validate:"cidr"`
	// Gateway is used to optionally set the default gateway for IPv4 or IPv6.
	Gateway *IPAddressCIDR `json:"gateway,omitempty" validate:"omitempty,cidr"`
	// Nameservers allows you to optionally specify nameservers for the interface.
	Nameservers []string `json:"nameservers" validate:"omitempty,dive,ip"`
}

StaticAddress specifies a static IP address configuration.

type VMID 

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

VMID represents the identifier for a microvm.

func NewVMID 

func NewVMID(name, namespace, uid string) (*VMID, error)

NewVMID creates a new VMID from a name, namespace and, UID.

func NewVMIDForce 

func NewVMIDForce(name, namespace, uid string) *VMID

NewVMIDForce creates a new VMID from a name, namespace, and UID, but without any checks. In case we want to create a new UID, but ignore checks.

func NewVMIDFromString 

func NewVMIDFromString(id string) (*VMID, error)

NewVMID creates a new VMID from a string.

func (*VMID) IsEmpty 

func (v *VMID) IsEmpty() bool

IsEmpty indicates that the id contains blank values.

func (*VMID) MarshalText 

func (v *VMID) MarshalText() (text []byte, err error)

MarshalText will marshall the vmid to a string representation.

func (*VMID) Name 

func (v *VMID) Name() string

Name returns the name part of the VMID.

func (*VMID) Namespace 

func (v *VMID) Namespace() string

Namespace returns the namespace part of the VMID.

func (*VMID) SetUID 

func (v *VMID) SetUID(uid string)

func (*VMID) String 

func (v *VMID) String() string

String returns a string representation of the vmid.

func (*VMID) UID 

func (v *VMID) UID() string

UID returns the UID part of the VMID.

func (*VMID) UnmarshalText 

func (v *VMID) UnmarshalText(text []byte) error

UnmarshalText will unmarshall the text into the vmid.

type VirtioFSVolumeSource added in v0.8.0 

type VirtioFSVolumeSource struct {
	// Image is the OCI image to use.
	Path string `json:"path"`
}

VirtioFSSource represents the details of the VirtioFS volume.

type Volume 

type Volume struct {
	// ID is the uinique identifier of the volume.
	ID string `json:"id"`
	// IsReadOnly specifies that the volume is to be mounted readonly. It is not supported
	// for a virtiofs volume, and a spec that sets it for one is rejected.
	IsReadOnly bool `json:"is_read_only,omitempty"`
	// Source is where the volume will be sourced from.
	Source VolumeSource `json:"source"`
	// PartitionID is the uuid of the boot partition.
	PartitionID string `json:"partition_id,omitempty"`
	// Size is the size to resize this volume to.
	Size int32 `json:"size,omitempty"`
	// MountPoint allows you to optionally specify a mount point for the volume. This only
	// applied to additional volumes and it will use cloud-init to mount the volumes.
	MountPoint string `json:"mount_point,omitempty"`
}

Volume represents a volume to be attached to a microvm machine.

type VolumeSource 

type VolumeSource struct {
	// Container is used to specify a source of a volume as a OCI container.
	Container *ContainerVolumeSource `json:"container,omitempty"`

	// Used to specify path for virtiofsd
	VirtioFS *VirtioFSVolumeSource `json:"virtiofs_source,omitempty"`
}

VolumeSource is the source of a volume. Based loosely on the volumes in Kubernetes Pod specs.

type VolumeStatus 

type VolumeStatus struct {
	// Mount is the mount point information for the volume.
	Mount Mount `json:"mount"`
}

VolumeStatus holds status information about the volumes.

type VolumeStatuses 

type VolumeStatuses map[string]*VolumeStatus

VolumeStatuses represents a collection of volume status.

type Volumes 

type Volumes []Volume

Volumes represents a collection of volumes.

func (Volumes) GetByID 

func (v Volumes) GetByID(id string) *Volume

GetByID will get a volume status by id.

func (Volumes) HasMountableVolumes 

func (v Volumes) HasMountableVolumes() bool

HasMountableVolumes returns true if any of the volumes have a mount point defined.

Source Files

View all Source files

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.