persistapi

package
v0.0.0-...-04f2983 Latest Latest
Warning

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

Go to latest
Published: May 5, 2021 License: Apache-2.0, Apache-2.0 Imports: 6 Imported by: 42

Documentation

Index

Constants

View Source
const (
	// CurPersistVersion is current persist data version.
	// This can help keep backward compatibility, if you make
	// some changes in persistapi package which needs different
	// handling process between different runtime versions, you
	// should modify `CurPersistVersion` and handle persist data
	// according to it.
	// If you can't be sure if the change in persistapi package
	// requires a bump of CurPersistVersion or not, do it for peace!
	// --@WeiZhang555
	CurPersistVersion uint = 2
)

Variables

This section is empty.

Functions

This section is empty.

Types

type AgentState

type AgentState struct {
	// Pid of proxy process
	ProxyPid int

	// URL to connect to agent
	URL string
}

AgentState save agent state data

type BlockDrive

type BlockDrive struct {
	// File is the path to the disk-image/device which will be used with this drive
	File string

	// Format of the drive
	Format string

	// ID is used to identify this drive in the hypervisor options.
	ID string

	// Index assigned to the drive. In case of virtio-scsi, this is used as SCSI LUN index
	Index int

	// MmioAddr is used to identify the slot at which the drive is attached (order?).
	MmioAddr string

	// PCIPath is the PCI path used to identify the slot at which the drive is attached.
	PCIPath vcTypes.PciPath

	// SCSI Address of the block device, in case the device is attached using SCSI driver
	// SCSI address is in the format SCSI-Id:LUN
	SCSIAddr string

	// NvdimmID is the nvdimm id inside the VM
	NvdimmID string

	// VirtPath at which the device appears inside the VM, outside of the container mount namespace
	VirtPath string

	// DevNo
	DevNo string

	// Pmem enabled persistent memory. Use File as backing file
	// for a nvdimm device in the guest.
	Pmem bool
}

BlockDrive represents a block storage drive which may be used in case the storage driver has an underlying block storage device.

type Bridge

type Bridge struct {
	// DeviceAddr contains information about devices plugged and its address in the bridge
	DeviceAddr map[uint32]string

	// Type is the type of the bridge (pci, pcie, etc)
	Type string

	//ID is used to identify the bridge in the hypervisor
	ID string

	// Addr is the PCI/e slot of the bridge
	Addr int
}

Bridge is a bridge where devices can be hot plugged

type BridgedMacvlanEndpoint

type BridgedMacvlanEndpoint struct {
	NetPair NetworkInterfacePair
}

type CPUDevice

type CPUDevice struct {
	// ID is used to identify this CPU in the hypervisor options.
	ID string
}

CPUDevice represents a CPU device which was hot-added in a running VM

type ContainerConfig

type ContainerConfig struct {
	ID          string
	Annotations map[string]string
	RootFs      string
	// Resources for recoding update
	Resources specs.LinuxResources
}

type ContainerState

type ContainerState struct {
	// State is container running status
	State string

	// Rootfs contains information of container rootfs
	Rootfs RootfsState

	// CgroupPath is the cgroup hierarchy where sandbox's processes
	// including the hypervisor are placed.
	CgroupPath string

	// DeviceMaps is mapping between sandbox device to dest in container
	DeviceMaps []DeviceMap

	// Mounts is mount info from OCI spec
	Mounts []Mount

	// Process on host representing container process
	Process Process

	// BundlePath saves container OCI config.json, which can be unmarshaled
	// and translated to "CompatOCISpec"
	BundlePath string
}

ContainerState represents container state

type DeviceMap

type DeviceMap struct {
	// ID reference to VM device
	ID string

	// ContainerPath is device path displayed in container
	ContainerPath string

	// FileMode permission bits for the device.
	FileMode os.FileMode

	// UID is user ID in the container namespace
	UID uint32

	// GID is group ID in the container namespace
	GID uint32
}

DeviceMap saves how host device maps to container device one hypervisor device can be Refs: virtcontainers/container.go:ContainerDevice

type DeviceState

type DeviceState struct {
	ID string

	// Type is used to specify driver type
	// Refs: virtcontainers/device/config/config.go:DeviceType
	Type string

	RefCount    uint
	AttachCount uint

	// Type of device: c, b, u or p
	// c , u - character(unbuffered)
	// p - FIFO
	// b - block(buffered) special file
	// More info in mknod(1).
	DevType string

	// Major, minor numbers for device.
	Major int64
	Minor int64

	// ColdPlug specifies whether the device must be cold plugged (true)
	// or hot plugged (false).
	ColdPlug bool

	// DriverOptions is specific options for each device driver
	// for example, for BlockDevice, we can set DriverOptions["blockDriver"]="virtio-blk"
	DriverOptions map[string]string

	// ============ device driver specific data ===========
	// BlockDrive is specific for block device driver
	BlockDrive *BlockDrive `json:",omitempty"`

	// VFIODev is specific VFIO device driver
	VFIODevs []*VFIODev `json:",omitempty"`

	// VhostUserDeviceAttrs is specific for vhost-user device driver
	VhostUserDev *VhostUserDeviceAttrs `json:",omitempty"`
}

DeviceState is sandbox level resource which represents host devices plugged to hypervisor, one Device can be shared among containers in POD Refs: virtcontainers/device/drivers/generic.go:GenericDevice

type HypervisorConfig

type HypervisorConfig struct {
	// NumVCPUs specifies default number of vCPUs for the VM.
	NumVCPUs uint32

	//DefaultMaxVCPUs specifies the maximum number of vCPUs for the VM.
	DefaultMaxVCPUs uint32

	// DefaultMem specifies default memory size in MiB for the VM.
	MemorySize uint32

	// DefaultBridges specifies default number of bridges for the VM.
	// Bridges can be used to hot plug devices
	DefaultBridges uint32

	// Msize9p is used as the msize for 9p shares
	Msize9p uint32

	// MemSlots specifies default memory slots the VM.
	MemSlots uint32

	// MemOffset specifies memory space for nvdimm device
	MemOffset uint32

	// VirtioFSCacheSize is the DAX cache size in MiB
	VirtioFSCacheSize uint32

	// KernelPath is the guest kernel host path.
	KernelPath string

	// ImagePath is the guest image host path.
	ImagePath string

	// InitrdPath is the guest initrd image host path.
	// ImagePath and InitrdPath cannot be set at the same time.
	InitrdPath string

	// FirmwarePath is the bios host path
	FirmwarePath string

	// MachineAccelerators are machine specific accelerators
	MachineAccelerators string

	// CPUFeatures are cpu specific features
	CPUFeatures string

	// HypervisorPath is the hypervisor executable host path.
	HypervisorPath string

	// HypervisorPathList is the list of hypervisor paths names allowed in annotations
	HypervisorPathList []string

	// HypervisorCtlPath is the hypervisor ctl executable host path.
	HypervisorCtlPath string

	// HypervisorCtlPathList is the list of hypervisor control paths names allowed in annotations
	HypervisorCtlPathList []string

	// HypervisorCtlPath is the hypervisor ctl executable host path.
	// JailerPath is the jailer executable host path.
	JailerPath string

	// JailerPathList is the list of jailer paths names allowed in annotations
	JailerPathList []string

	// BlockDeviceDriver specifies the driver to be used for block device
	// either VirtioSCSI or VirtioBlock with the default driver being defaultBlockDriver
	BlockDeviceDriver string

	// HypervisorMachineType specifies the type of machine being
	// emulated.
	HypervisorMachineType string

	// MemoryPath is the memory file path of VM memory. Used when either BootToBeTemplate or
	// BootFromTemplate is true.
	MemoryPath string

	// DevicesStatePath is the VM device state file path. Used when either BootToBeTemplate or
	// BootFromTemplate is true.
	DevicesStatePath string

	// EntropySource is the path to a host source of
	// entropy (/dev/random, /dev/urandom or real hardware RNG device)
	EntropySource string

	// Shared file system type:
	//   - virtio-9p (default)
	//   - virtio-fs
	SharedFS string

	// VirtioFSDaemon is the virtio-fs vhost-user daemon path
	VirtioFSDaemon string

	// VirtioFSDaemonList is the list of valid virtiofs names for annotations
	VirtioFSDaemonList []string

	// VirtioFSCache cache mode for fs version cache or "none"
	VirtioFSCache string

	// VirtioFSExtraArgs passes options to virtiofsd daemon
	VirtioFSExtraArgs []string

	// File based memory backend root directory
	FileBackedMemRootDir string

	// FileBackedMemRootList is the list of valid root directories values for annotations
	FileBackedMemRootList []string

	// BlockDeviceCacheSet specifies cache-related options will be set to block devices or not.
	BlockDeviceCacheSet bool

	// BlockDeviceCacheDirect specifies cache-related options for block devices.
	// Denotes whether use of O_DIRECT (bypass the host page cache) is enabled.
	BlockDeviceCacheDirect bool

	// BlockDeviceCacheNoflush specifies cache-related options for block devices.
	// Denotes whether flush requests for the device are ignored.
	BlockDeviceCacheNoflush bool

	// DisableBlockDeviceUse disallows a block device from being used.
	DisableBlockDeviceUse bool

	// EnableIOThreads enables IO to be processed in a separate thread.
	// Supported currently for virtio-scsi driver.
	EnableIOThreads bool

	// Debug changes the default hypervisor and kernel parameters to
	// enable debug output where available.
	Debug bool

	// MemPrealloc specifies if the memory should be pre-allocated
	MemPrealloc bool

	// HugePages specifies if the memory should be pre-allocated from huge pages
	HugePages bool

	// VirtioMem is used to enable/disable virtio-mem
	VirtioMem bool

	// Realtime Used to enable/disable realtime
	Realtime bool

	// Mlock is used to control memory locking when Realtime is enabled
	// Realtime=true and Mlock=false, allows for swapping out of VM memory
	// enabling higher density
	Mlock bool

	// DisableNestingChecks is used to override customizations performed
	// when running on top of another VMM.
	DisableNestingChecks bool

	// UseVSock use a vsock for agent communication
	UseVSock bool

	// DisableImageNvdimm disables nvdimm for guest rootfs image
	DisableImageNvdimm bool

	// HotplugVFIOOnRootBus is used to indicate if devices need to be hotplugged on the
	// root bus instead of a bridge.
	HotplugVFIOOnRootBus bool

	// PCIeRootPort is used to indicate the number of PCIe Root Port devices
	// The PCIe Root Port device is used to hot-plug the PCIe device
	PCIeRootPort uint32

	// BootToBeTemplate used to indicate if the VM is created to be a template VM
	BootToBeTemplate bool

	// BootFromTemplate used to indicate if the VM should be created from a template VM
	BootFromTemplate bool

	// DisableVhostNet is used to indicate if host supports vhost_net
	DisableVhostNet bool

	// EnableVhostUserStore is used to indicate if host supports vhost-user-blk/scsi
	EnableVhostUserStore bool

	// VhostUserStorePath is the directory path where vhost-user devices
	// related folders, sockets and device nodes should be.
	VhostUserStorePath string

	// VhostUserStorePathList is the list of valid values for vhost-user paths
	VhostUserStorePathList []string

	// GuestHookPath is the path within the VM that will be used for 'drop-in' hooks
	GuestHookPath string

	// VMid is the id of the VM that create the hypervisor if the VM is created by the factory.
	// VMid is "" if the hypervisor is not created by the factory.
	VMid string

	// Enable annotations by name
	EnableAnnotations []string
}

HypervisorConfig saves configurations of sandbox hypervisor

type HypervisorState

type HypervisorState struct {
	Pid int
	// Type of hypervisor, E.g. qemu/firecracker/acrn.
	Type          string
	BlockIndexMap map[int]struct{}
	UUID          string

	// Belows are qemu specific
	// Refs: virtcontainers/qemu.go:QemuState
	Bridges []Bridge
	// HotpluggedCPUs is the list of CPUs that were hot-added
	HotpluggedVCPUs      []CPUDevice
	HotpluggedMemory     int
	VirtiofsdPid         int
	HotplugVFIOOnRootBus bool
	PCIeRootPort         int

	// clh sepcific: refer to 'virtcontainers/clh.go:CloudHypervisorState'
	APISocket string
}

type IPVlanEndpoint

type IPVlanEndpoint struct {
	NetPair NetworkInterfacePair
}

type KataAgentConfig

type KataAgentConfig struct {
	LongLiveConn bool
	UseVSock     bool
}

KataAgentConfig is a structure storing information needed to reach the Kata Containers agent.

type MacvtapEndpoint

type MacvtapEndpoint struct {
	// This is for showing information.
	// Remove this field won't impact anything.
	PCIPath vcTypes.PciPath
}

type Mount

type Mount struct {
	Source      string
	Destination string

	// Type specifies the type of filesystem to mount.
	Type string

	// Options list all the mount options of the filesystem.
	Options []string

	// HostPath used to store host side bind mount path
	HostPath string

	// ReadOnly specifies if the mount should be read only or not
	ReadOnly bool

	// BlockDeviceID represents block device that is attached to the
	// VM in case this mount is a block device file or a directory
	// backed by a block device.
	BlockDeviceID string
}

Mount describes a container mount.

type NetworkConfig

type NetworkConfig struct {
	NetNSPath         string
	NetNsCreated      bool
	DisableNewNetNs   bool
	InterworkingModel int
}

NetworkConfig is the network configuration related to a network.

type NetworkEndpoint

type NetworkEndpoint struct {
	Type string

	// One and only one of these below are not nil according to Type.
	Physical       *PhysicalEndpoint       `json:",omitempty"`
	Veth           *VethEndpoint           `json:",omitempty"`
	VhostUser      *VhostUserEndpoint      `json:",omitempty"`
	BridgedMacvlan *BridgedMacvlanEndpoint `json:",omitempty"`
	Macvtap        *MacvtapEndpoint        `json:",omitempty"`
	Tap            *TapEndpoint            `json:",omitempty"`
	IPVlan         *IPVlanEndpoint         `json:",omitempty"`
	Tuntap         *TuntapEndpoint         `json:",omitempty"`
}

NetworkEndpoint contains network interface information

type NetworkInfo

type NetworkInfo struct {
	NetNsPath    string
	NetmonPID    int
	NetNsCreated bool
	Endpoints    []NetworkEndpoint
}

NetworkInfo contains network information of sandbox

type NetworkInterface

type NetworkInterface struct {
	Name     string
	HardAddr string
	Addrs    []netlink.Addr
}

type NetworkInterfacePair

type NetworkInterfacePair struct {
	TapInterface
	VirtIface            NetworkInterface
	NetInterworkingModel int
}

NetworkInterfacePair defines a pair between VM and virtual network interfaces.

type PersistDriver

type PersistDriver interface {
	// ToDisk flushes data to disk(or other storage media such as a remote db)
	ToDisk(SandboxState, map[string]ContainerState) error
	// FromDisk will restore all data for sandbox with `sid` from storage.
	// We only support get data for one whole sandbox
	FromDisk(sid string) (SandboxState, map[string]ContainerState, error)
	// Destroy will remove everything from storage
	Destroy(sid string) error
	// Lock locks the persist driver, "exclusive" decides whether the lock is exclusive or shared.
	// It returns Unlock Function and errors
	Lock(sid string, exclusive bool) (func() error, error)

	// GlobalWrite writes "data" to "StorageRootPath"/"relativePath";
	// GlobalRead reads "data" from "StorageRootPath"/"relativePath";
	// these functions are used for writing/reading some global data,
	// they are specially designed for ACRN so far.
	// Don't use them too much unless you have no other choice! @weizhang555
	GlobalWrite(relativePath string, data []byte) error
	GlobalRead(relativePath string) ([]byte, error)

	// RunStoragePath is the sandbox runtime directory.
	// It will contain one state.json and one lock file for each created sandbox.
	RunStoragePath() string

	// RunVMStoragePath is the vm directory.
	// It will contain all guest vm sockets and shared mountpoints.
	RunVMStoragePath() string
}

PersistDriver is interface describing operations to save/restore persist data

type PhysicalEndpoint

type PhysicalEndpoint struct {
	BDF            string
	Driver         string
	VendorDeviceID string
}

type Process

type Process struct {
	// Token is the process execution context ID. It must be
	// unique per sandbox.
	// Token is used to manipulate processes for containers
	// that have not started yet, and later identify them
	// uniquely within a sandbox.
	Token string

	// Pid is the process ID as seen by the host software
	// stack, e.g. CRI-O, containerd. This is typically the
	// shim PID.
	Pid int

	StartTime time.Time
}

Process gathers data related to a container process. Refs: virtcontainers/container.go:Process

type ProxyConfig

type ProxyConfig struct {
	Path  string
	Debug bool
}

ProxyConfig is a structure storing information needed from any proxy in order to be properly initialized.

type RootfsState

type RootfsState struct {
	// BlockDeviceID represents container rootfs block device ID
	// when backed by devicemapper
	BlockDeviceID string

	// RootFStype is file system of the rootfs incase it is block device
	FsType string
}

RootfsState saves state of container rootfs

type SandboxConfig

type SandboxConfig struct {
	HypervisorType   string
	HypervisorConfig HypervisorConfig

	// only one agent config can be non-nil according to agent type
	AgentType       string
	KataAgentConfig *KataAgentConfig `json:",omitempty"`

	ProxyType   string
	ProxyConfig ProxyConfig

	ShimType       string
	KataShimConfig *ShimConfig

	NetworkConfig NetworkConfig

	ShmSize uint64

	// SharePidNs sets all containers to share the same sandbox level pid namespace.
	SharePidNs bool

	// Stateful keeps sandbox resources in memory across APIs. Users will be responsible
	// for calling Release() to release the memory resources.
	Stateful bool

	// SystemdCgroup enables systemd cgroup support
	SystemdCgroup bool

	// SandboxCgroupOnly enables cgroup only at podlevel in the host
	SandboxCgroupOnly bool

	// Determines if containers are allowed to join the pid namespace of the kata agent
	EnableAgentPidNs bool

	DisableGuestSeccomp bool

	// Experimental enables experimental features
	Experimental []string

	ContainerConfigs []ContainerConfig

	// Cgroups specifies specific cgroup settings for the various subsystems that the container is
	// placed into to limit the resources the container has available
	Cgroups *configs.Cgroup `json:"cgroups"`
}

SandboxConfig is a sandbox configuration. Refs: virtcontainers/sandbox.go:SandboxConfig

type SandboxState

type SandboxState struct {
	// PersistVersion of persist data format, can be used for keeping compatibility later
	PersistVersion uint

	// State is sandbox running status
	State string

	// GuestMemoryBlockSizeMB is the size of memory block of guestos
	GuestMemoryBlockSizeMB uint32

	// GuestMemoryHotplugProbe determines whether guest kernel supports memory hotplug probe interface
	GuestMemoryHotplugProbe bool

	// SandboxContainer specifies which container is used to start the sandbox/vm
	SandboxContainer string

	// CgroupPath is the cgroup hierarchy where sandbox's processes
	// including the hypervisor are placed.
	// FIXME: sandbox can reuse "SandboxContainer"'s CgroupPath so we can remove this field.
	CgroupPath string

	// CgroupPath is the cgroup hierarchy where sandbox's processes
	// including the hypervisor are placed.
	CgroupPaths map[string]string

	// Devices plugged to sandbox(hypervisor)
	Devices []DeviceState

	// HypervisorState saves hypervisor specific data
	HypervisorState HypervisorState

	// AgentState saves state data of agent
	AgentState AgentState

	// Network saves network configuration of sandbox
	Network NetworkInfo

	// Config saves config information of sandbox
	Config SandboxConfig
}

SandboxState contains state information of sandbox nolint: maligned

type ShimConfig

type ShimConfig struct {
	Path  string
	Debug bool
}

ShimConfig is the structure providing specific configuration for shim implementation.

type TapEndpoint

type TapEndpoint struct {
	TapInterface TapInterface
}

type TapInterface

type TapInterface struct {
	ID       string
	Name     string
	TAPIface NetworkInterface
}

TapInterface defines a tap interface

type TuntapEndpoint

type TuntapEndpoint struct {
	TuntapInterface TuntapInterface
}

type TuntapInterface

type TuntapInterface struct {
	Name     string
	TAPIface NetworkInterface
}

TuntapInterface defines a tap interface

type VFIODev

type VFIODev struct {
	// ID is used to identify this drive in the hypervisor options.
	ID string

	// Type of VFIO device
	Type uint32

	// BDF (Bus:Device.Function) of the PCI address
	BDF string

	// Sysfsdev of VFIO mediated device
	SysfsDev string
}

VFIODev represents a VFIO drive used for hotplugging

type VethEndpoint

type VethEndpoint struct {
	NetPair NetworkInterfacePair
}

type VhostUserDeviceAttrs

type VhostUserDeviceAttrs struct {
	DevID      string
	SocketPath string
	Type       string

	// MacAddress is only meaningful for vhost user net device
	MacAddress string

	// PCIPath is the PCI path used to identify the slot at which the drive is attached.
	// It is only meaningful for vhost user block devices
	PCIPath vcTypes.PciPath

	// Block index of the device if assigned
	Index int
}

VhostUserDeviceAttrs represents data shared by most vhost-user devices

type VhostUserEndpoint

type VhostUserEndpoint struct {
	// This is for showing information.
	// Remove these fields won't impact anything.
	IfaceName string
	PCIPath   vcTypes.PciPath
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL