persist: baseline persist data format

Fixes kata-containers#803

The disk persist data should be "versioned" and baselined, any modification in
persist data should be considered potential break of backward compatibility.

Signed-off-by: Wei Zhang <[email protected]>

virtcontainers/persist/api/container.go

@@ -0,0 +1,109 @@
+// Copyright (c) 2018 Huawei Corporation
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+package persistapi
+
+import (
+	"os"
+	"time"
+)
+
+// ============= container level resources =============
+
+// DeviceMap saves how host device maps to container device
+// one hypervisor device can be
+// Refs: virtcontainers/container.go:ContainerDevice
+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
+}
+
+// Mount describes a container 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
+}
+
+// RootfsState saves state of container rootfs
+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
+	RootFSType string
+}
+
+// Process gathers data related to a container process.
+// Refs: virtcontainers/container.go: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
+}
+
+// ContainerState represents container state
+type ContainerState struct {
+	// State is container running status
+	State string
+
+	// Rootfs contains information of container rootfs
+	Rootfs RootfsState
+
+	// ShimPid is pid of shim process for each container
+	ShimPid int
+
+	// GuestMemoryBlockSizeMB is the size of memory block of guestos
+	GuestMemoryBlockSizeMB uint32
+
+	// 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
+	// FIXME: []Process or Process ?
+	Process []Process
+}

virtcontainers/persist/api/device.go

@@ -0,0 +1,102 @@
+// Copyright (c) 2018 Huawei Corporation
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+package persistapi
+
+// ============= sandbox level resources =============
+
+// BlockDrive represents a block storage drive which may be used in case the storage
+// driver has an underlying block storage device.
+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
+
+	// PCIAddr is the PCI address used to identify the slot at which the drive is attached.
+	PCIAddr string
+
+	// 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
+
+	// VirtPath at which the device appears inside the VM, outside of the container mount namespace
+	VirtPath string
+}
+
+// VFIODev represents a VFIO drive used for hotplugging
+type VFIODev struct {
+	// ID is used to identify this drive in the hypervisor options.
+	ID string
+
+	// Type of VFIO device
+	Type string
+
+	// BDF (Bus:Device.Function) of the PCI address
+	BDF string
+
+	// Sysfsdev of VFIO mediated device
+	SysfsDev string
+}
+
+// VhostUserDeviceAttrs represents data shared by most vhost-user devices
+type VhostUserDeviceAttrs struct {
+	DevID      string
+	SocketPath string
+	Type       string
+
+	// MacAddress is only meaningful for vhost user net device
+	MacAddress string
+}
+
+// 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 DeviceState struct {
+	ID string
+
+	// Type is used to specify driver type
+	// Refs: virtcontainers/device/config/config.go:DeviceType
+	Type string
+
+	RefCount    uint
+	AttachCount uint
+
+	// Hostpath is device path on host
+	HostPath string
+
+	// 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
+
+	// 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"`
+	// ============ end device driver specific data ===========
+}

virtcontainers/persist/api/network.go

@@ -0,0 +1,24 @@
+// Copyright (c) 2018 Huawei Corporation
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+package persistapi
+
+// ============= sandbox level resources =============
+
+// NetworkEndpoint contains network interface information
+type NetworkEndpoint struct {
+	Type string
+
+	// TODO: add fields from virtcontainers/*_endpoint.go
+	// it's a chaos now
+}
+
+// NetworkInfo contains network information of sandbox
+type NetworkInfo struct {
+	NetNsPath    string
+	NetNsCreated bool
+	NetmonPID    int
+	Endpoints    []NetworkEndpoint
+}

virtcontainers/persist/api/sandbox.go

@@ -0,0 +1,73 @@
+// Copyright (c) 2018 Huawei Corporation
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+package persistapi
+
+// ============= sandbox level resources =============
+
+type SettingFunc (func(*SandboxState, map[string]ContainerState) error)
+
+// Bridge is a bridge where devices can be hot plugged
+type Bridge struct {
+	// Address 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
+}
+
+// CPUDevice represents a CPU device which was hot-added in a running VM
+type CPUDevice struct {
+	// ID is used to identify this CPU in the hypervisor options.
+	ID string
+}
+
+// HypervisorState saves state of hypervisor
+// Refs: virtcontainers/qemu.go:QemuState
+type HypervisorState struct {
+	Pid     int
+	Bridges []Bridge
+	// HotpluggedCPUs is the list of CPUs that were hot-added
+	HotpluggedVCPUs      []CPUDevice
+	HotpluggedMemory     int
+	UUID                 string
+	HotplugVFIOOnRootBus bool
+}
+
+// ProxyState save proxy state data
+type ProxyState struct {
+	// Pid of proxy process
+	Pid int
+
+	// URL to connect to proxy
+	URL string
+}
+
+// SandboxState contains state information of sandbox
+type SandboxState struct {
+	// version of persist data format, can be used for keeping compatibility later
+	PersistVersion uint
+
+	// SandboxContainer specifies which container is used to start the sandbox/vm
+	SandboxContainer string
+
+	// Devices plugged to sandbox(hypervisor)
+	Devices []DeviceState
+
+	// HypervisorState saves hypervisor specific data
+	HypervisorState HypervisorState
+
+	// ProxyState saves state data of proxy process
+	ProxyState ProxyState
+
+	// Network saves network configuration of sandbox
+	Network NetworkInfo
+}

virtcontainers/persist/api/version.go

@@ -0,0 +1,19 @@
+// Copyright (c) 2018 Huawei Corporation
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+package persistapi
+
+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 = 1
+)