types

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Oct 18, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Overview

Package types defines shared data types used across snapshot packages.

Index

Constants

View Source
const (
	CuInterposeFrontend = "libcuinterpose.so"
	CuInterposeCore     = "libcuinterpose_core.so"
)
View Source
const CheckpointBasePath = "/checkpoints"

CheckpointBasePath is the fixed agent-side checkpoint mount. The privileged helper independently enforces the same path.

View Source
const DefaultCheckpointTimeoutSeconds = 3600

DefaultCheckpointTimeoutSeconds bounds a dump for a config written before the field existed.

Variables

View Source
var CuInterposeLibraries = []string{CuInterposeFrontend, CuInterposeCore}

CuInterposeLibraries lists every shim library whose hash the manifest records.

Functions

func WriteManifest

func WriteManifest(checkpointDir string, data *CheckpointManifest) error

WriteManifest writes a checkpoint manifest file in the checkpoint directory.

Types

type AgentConfig

type AgentConfig struct {
	NodeName               string          `yaml:"-"`
	HostKernelVersion      string          `yaml:"-"`
	CustomStorageAvailable bool            `yaml:"-"`
	Storage                StorageSpec     `yaml:"storage"`
	Overlay                OverlaySettings `yaml:"overlay"`
	PageBroker             PageBrokerSpec  `yaml:"pageBroker"`
	Checkpoint             CheckpointSpec  `yaml:"checkpoint"`
	Restore                RestoreSpec     `yaml:"restore"`
	CRIU                   CRIUSettings    `yaml:"criu"`
}

AgentConfig holds static checkpoint settings plus runtime fields populated at startup.

func (*AgentConfig) LoadEnvOverrides

func (c *AgentConfig) LoadEnvOverrides()

func (*AgentConfig) Validate

func (c *AgentConfig) Validate() error

type ArtifactManifest

type ArtifactManifest struct {
	ContentUID    string `yaml:"contentUID"`
	ContainerName string `yaml:"containerName"`
}

ArtifactManifest pins an on-disk checkpoint to the Kubernetes content object and container whose immutable identity determines its path.

type CRIUDumpManifest

type CRIUDumpManifest struct {
	CRIU     CRIUSettings      `yaml:"criu"`
	ExtMnt   map[string]string `yaml:"extMnt,omitempty"`
	External []string          `yaml:"external,omitempty"`
	SkipMnt  []string          `yaml:"skipMnt,omitempty"`
}

CRIUDumpManifest stores the resolved dump-time CRIU mount plan used for restore.

func NewCRIUDumpManifest

func NewCRIUDumpManifest(criuOpts *criurpc.CriuOpts, settings CRIUSettings) CRIUDumpManifest

type CRIUSettings

type CRIUSettings struct {
	GhostLimit        uint32 `yaml:"ghostLimit"`
	LogLevel          int32  `yaml:"logLevel"`
	WorkDir           string `yaml:"workDir"`
	AutoDedup         bool   `yaml:"autoDedup"`
	LazyPages         bool   `yaml:"lazyPages"`
	ShellJob          bool   `yaml:"shellJob"`
	TcpClose          bool   `yaml:"tcpClose"`
	TcpEstablished    bool   `yaml:"tcpEstablished"`
	FileLocks         bool   `yaml:"fileLocks"`
	OrphanPtsMaster   bool   `yaml:"orphanPtsMaster"`
	ExtUnixSk         bool   `yaml:"extUnixSk"`
	LinkRemap         bool   `yaml:"linkRemap"`
	ExtMasters        bool   `yaml:"extMasters"`
	ManageCgroupsMode string `yaml:"manageCgroupsMode"`
	ImageIoMode       string `yaml:"imageIoMode"`
	RstSibling        bool   `yaml:"rstSibling"`
	MntnsCompatMode   bool   `yaml:"mntnsCompatMode"`
	EvasiveDevices    bool   `yaml:"evasiveDevices"`
	ForceIrmap        bool   `yaml:"forceIrmap"`
	BinaryPath        string `yaml:"binaryPath"`
	LibDir            string `yaml:"libDir"`
	AllowUprobes      bool   `yaml:"allowUprobes"`
	SkipInFlight      bool   `yaml:"skipInFlight"`
}

CRIUSettings holds CRIU-specific configuration options.

type CUDAManifest

type CUDAManifest struct {
	// CustomStorage stores GPU data through the embedded PageBroker GPU engine.
	CustomStorage        bool              `yaml:"customStorage,omitempty"`
	PIDs                 []int             `yaml:"pids"`
	SourceGPUUUIDs       []string          `yaml:"sourceGpuUuids"`
	DevicePaths          map[string]string `yaml:"devicePaths,omitempty"`
	NVIDIAVisibleDevices *string           `yaml:"nvidiaVisibleDevices,omitempty"`

	// SourceGPUs describes the same GPUs as SourceGPUUUIDs, in the same order.
	// The UUIDs stay where they are because the device map is built from them
	// and artifacts written before this field exists still restore.
	SourceGPUs          []GPUManifest `yaml:"sourceGpus,omitempty"`
	SourceDriverVersion string        `yaml:"sourceDriverVersion,omitempty"`
}

CUDAManifest captures CUDA state from checkpoint time for restore.

func NewCUDAManifest

func NewCUDAManifest(pids []int, gpus compat.GPUInfo) CUDAManifest

func (CUDAManifest) IsEmpty

func (m CUDAManifest) IsEmpty() bool

type CheckpointContainerSnapshot

type CheckpointContainerSnapshot struct {
	PID            int
	ImageID        string
	RootFS         string
	UpperDir       string
	OCISpec        *specs.Spec
	Mounts         []MountInfo
	NetNSInode     uint64
	StdioFDs       []string // readlink targets for FDs 0, 1, 2 (e.g. "pipe:[12345]")
	HostCgroupPath string   // host filesystem path for CRIU's --freeze-cgroup
	CUDAHostPIDs   []int    // host-visible PIDs used for checkpoint-side CUDA actions
	CUDANSPIDs     []int    // namespace-relative PIDs stored in the checkpoint manifest
	GPUDevicePaths map[string]string
	CuInterpose    *CuInterposeManifest

	// GPUs holds the GPUs the checkpointed container could see, in allocation
	// order, with the model and driver version where they could be read.
	GPUs compat.GPUInfo
}

CheckpointContainerSnapshot holds runtime container state collected during checkpoint inspection.

type CheckpointManifest

type CheckpointManifest struct {
	Artifact  ArtifactManifest `yaml:"artifact"`
	CreatedAt time.Time        `yaml:"createdAt"`

	CRIUDump CRIUDumpManifest  `yaml:"criuDump"`
	K8s      SourcePodManifest `yaml:"k8s"`
	Overlay  OverlayManifest   `yaml:"overlay"`
	CUDA     CUDAManifest      `yaml:"cudaRestore,omitempty"`
	Host     HostManifest      `yaml:"host,omitempty"`
	// CuInterpose identifies the libraries verified in the source processes.
	CuInterpose *CuInterposeManifest `yaml:"cuinterpose,omitempty"`
}

CheckpointManifest is saved as manifest.yaml at checkpoint time and loaded at restore.

func NewCheckpointManifest

func NewCheckpointManifest(
	contentUID string,
	containerName string,
	criuDump CRIUDumpManifest,
	k8s SourcePodManifest,
	overlay OverlayManifest,
	host HostManifest,
) *CheckpointManifest

func ReadManifest

func ReadManifest(checkpointDir string) (*CheckpointManifest, error)

ReadManifest reads checkpoint manifest from a checkpoint directory.

func (*CheckpointManifest) CompatEnvironment added in v0.2.0

func (m *CheckpointManifest) CompatEnvironment() compat.Environment

CompatEnvironment maps the manifest onto what the compatibility gates compare. Both gates read it from here, so the two cannot disagree about what the checkpoint recorded.

type CheckpointSpec added in v0.2.0

type CheckpointSpec struct {
	// A pointer so absent and zero are distinguishable: every config predating this field omits
	// it, and an agent upgraded ahead of its ConfigMap has to start — with the guard on.
	CheckpointTimeoutSeconds *int `yaml:"checkpointTimeoutSeconds"`
}

CheckpointSpec holds settings for the CRIU dump.

func (*CheckpointSpec) CheckpointTimeout added in v0.2.0

func (c *CheckpointSpec) CheckpointTimeout() time.Duration

CheckpointTimeout bounds one dump, defaulting when the config omits it.

func (*CheckpointSpec) Validate added in v0.2.0

func (c *CheckpointSpec) Validate() error

type ConfigError

type ConfigError struct {
	Field   string
	Message string
}

ConfigError represents a configuration validation error.

func (*ConfigError) Error

func (e *ConfigError) Error() string

type CuInterposeLibraryIdentity added in v0.2.0

type CuInterposeLibraryIdentity struct {
	SHA256 string `yaml:"sha256"`
}

CuInterposeLibraryIdentity identifies a delivered shim library.

type CuInterposeManifest added in v0.2.0

type CuInterposeManifest struct {
	// Libraries maps each delivered shim library file name to its identity.
	Libraries map[string]CuInterposeLibraryIdentity `yaml:"libraries"`
	// PIDs are the innermost namespace PIDs whose core serves a coordinator endpoint.
	// An explicit empty list means CUDA processes loaded only the frontend.
	PIDs []int `yaml:"pids"`
}

CuInterposeManifest records the shim libraries a checkpoint was captured with and the processes whose core serves a coordinator endpoint.

func (*CuInterposeManifest) UsesCoordinator added in v0.2.0

func (m *CuInterposeManifest) UsesCoordinator() bool

UsesCoordinator reports whether any process initialized the core and therefore serves a coordinator endpoint. Library identity and restore delivery apply even when only the frontend was loaded.

func (*CuInterposeManifest) Validate added in v0.2.0

func (m *CuInterposeManifest) Validate() error

Validate checks the library hashes and the PID list.

type GPUManifest added in v0.2.0

type GPUManifest struct {
	UUID        string `yaml:"uuid"`
	ProductName string `yaml:"productName,omitempty"`
}

GPUManifest is one GPU the checkpointed process could see.

type HostManifest added in v0.2.0

type HostManifest struct {
	KernelVersion string `yaml:"kernelVersion,omitempty"`
	CPUArch       string `yaml:"cpuArch,omitempty"`
}

HostManifest records the machine a checkpoint was captured on. A value the agent could not read is left out rather than written empty, so it reads as unknown instead of as a value that happens to be blank.

func NewHostManifest added in v0.2.0

func NewHostManifest(kernelVersion string) HostManifest

NewHostManifest takes the architecture from the agent binary rather than asking the node: this binary is running on that node, so they agree.

type MountInfo

type MountInfo struct {
	MountPoint string
	FSType     string
	VFSOptions string // superblock options (e.g. "upperdir=...")
	ReadOnly   bool   // per-mount "ro" option, which CRIU reapplies on restore

	// IsOCIManaged is true when the mount destination matches an OCI spec entry
	// (including /run/ ↔ /var/run/ aliasing). Set by ClassifyMounts.
	IsOCIManaged bool
}

MountInfo holds parsed mount information from /proc/pid/mountinfo.

type OverlayManifest

type OverlayManifest struct {
	Exclusions     OverlaySettings `yaml:"exclusions"`
	UpperDir       string          `yaml:"upperDir,omitempty"`
	ExternalPaths  []string        `yaml:"externalPaths,omitempty"`
	BindMountDests []string        `yaml:"bindMountDests,omitempty"`
}

OverlayManifest holds runtime overlay state captured at checkpoint time.

func NewOverlayManifest

func NewOverlayManifest(exclusions OverlaySettings, upperDir string, ociSpec *specs.Spec) OverlayManifest

type OverlaySettings

type OverlaySettings struct {
	Exclusions []string `yaml:"exclusions"`
}

OverlaySettings is the static config for rootfs exclusions.

type PageBrokerSpec added in v0.2.0

type PageBrokerSpec struct {
	// RestoreMode selects the restore source. Empty defaults to direct.
	RestoreMode       string `yaml:"restoreMode"`
	ControlSocketPath string `yaml:"controlSocketPath"`
}

type RestoreContainerSnapshot

type RestoreContainerSnapshot struct {
	TargetGPUUUIDs  []string
	PlaceholderPID  int
	TargetRoot      string
	CgroupRoot      string
	CUDADeviceMap   string
	GPUMountAliases map[string]string
}

RestoreContainerSnapshot holds inspected state for the restore target.

type RestoreSpec

type RestoreSpec struct {
	RestoreTimeoutSeconds int `yaml:"restoreTimeoutSeconds"`

	// SkipCompatCheck turns the restore compatibility gate off for every
	// restore this agent handles. It is the per-node escape hatch, for a
	// cluster admin who would otherwise be stuck annotating pods one by one.
	SkipCompatCheck bool `yaml:"skipCompatCheck"`
}

RestoreSpec holds settings for the CRIU restore process.

func (*RestoreSpec) RestoreTimeout

func (c *RestoreSpec) RestoreTimeout() time.Duration

func (*RestoreSpec) Validate

func (c *RestoreSpec) Validate() error

type SourcePodManifest

type SourcePodManifest struct {
	ContainerID  string `yaml:"containerId"`
	PID          int    `yaml:"pid"`
	SourceNode   string `yaml:"sourceNode"`
	PodName      string `yaml:"podName"`
	PodNamespace string `yaml:"podNamespace"`
	PodIP        string `yaml:"podIP,omitempty"`

	// StdioFDs holds readlink targets for FDs 0, 1, 2 (e.g. "pipe:[12345]").
	StdioFDs []string `yaml:"stdioFDs,omitempty"`

	// ImageID is CRI ContainerStatus.image_id, not kubelet's image_ref alias.
	Image       string `yaml:"image,omitempty"`
	ImageID     string `yaml:"imageId,omitempty"`
	CPULimit    string `yaml:"cpuLimit,omitempty"`
	MemoryLimit string `yaml:"memoryLimit,omitempty"`
}

SourcePodManifest records the source pod identity at checkpoint time.

func NewSourcePodManifest

func NewSourcePodManifest(containerID string, pid int, sourceNode, podName, podNamespace, podIP string, stdioFDs []string) SourcePodManifest

func (SourcePodManifest) WithPodEnvironment added in v0.2.0

func (m SourcePodManifest) WithPodEnvironment(env compat.Environment) SourcePodManifest

WithPodEnvironment records what the captured container ran as. It is the inverse of the pod half of CompatEnvironment, and sits next to it so the two field lists cannot drift apart.

type StorageSpec

type StorageSpec struct {
	Type     string `yaml:"type"`
	BasePath string `yaml:"basePath"`
}

StorageSpec holds snapshot storage settings that are local to the agent deployment.

Jump to

Keyboard shortcuts

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