Documentation
¶
Overview ¶
Package compat compares what a checkpoint was captured on against what a restore target offers, so an incompatible restore is refused up front instead of failing deep inside CRIU with an unattributable error.
The node agent is the only consumer today. It sits in the api module because the check names are protocol, published verbatim on pod conditions and events, and so the operator can surface the same recorded environment on the content status without a second vocabulary growing up beside this one.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ImageDigest ¶
ImageDigest reduces a container status image ID to the digest inside it. Runtimes disagree on the wrapping - containerd reports a bare "sha256:...", others a scheme and a repository around it - and the artifact keeps whichever form it was given, so the two are only comparable after this.
Exported so that what a checkpoint publishes is the same reduction this compares, rather than a second one that can disagree with it.
func InstructionSetFeatures ¶ added in v0.3.0
InstructionSetFeatures keeps the instruction-set flags out of a CPU's flags, sorted and without duplicates. The rest describe the machine rather than what runs on it - hypervisor, constant_tsc, the vulnerability workarounds - and differ between nodes a process moves between freely, so comparing them would refuse restores that work. A CPU with none of them is unknown, so the result is then nil.
Types ¶
type Check ¶
type Check string
Check identifies one comparison rule. It is reported verbatim to users and to tooling that branches on it, so a name never changes once released.
const CheckCPUArch Check = "cpu-arch"
CheckCPUArch refuses a restore onto a different instruction set. A checkpoint holds register state, and CRIU has nowhere to put an x86 register file on an ARM core, so this one can never be waived by a bigger machine or a newer driver - it is the hardest of the rules.
const CheckCPUFeatures Check = "cpu-features"
CheckCPUFeatures refuses a CPU missing an instruction set the source had: the restored process keeps its startup code paths and would die of SIGILL.
const CheckCPULimit Check = "cpu-limit"
CheckCPULimit refuses a restore into less CPU than the checkpoint was captured with. Unlike memory, too little does not fail: the workload restores, reports success, and runs measurably slower forever, which is the worst outcome of the three because nothing says it happened.
const CheckDriverMinimum Check = "driver-minimum"
CheckDriverMinimum refuses a driver older than CUDA checkpoint and restore is supported on at all.
const CheckDriverVersion Check = "driver-version"
CheckDriverVersion refuses a restore on a driver build other than the captured one. Build granularity is not caution for its own sake: upstream reproduces a restore failure between 560.35.03 and 560.35.05.
const CheckGPUCount Check = "gpu-count"
CheckGPUCount refuses a restore onto a different number of GPUs. A multi-GPU checkpoint holds one piece of device state per GPU with a rank each, and there is no meaning to be given to a rank that has nowhere to land - or to a GPU no rank was recorded for.
A target discovery read as having no GPUs is that same refusal. A target with no GPU stack to read does not reach here at all: discovery fails first and the restore carries that error instead.
const CheckGPUModel Check = "gpu-model"
CheckGPUModel refuses a restore onto a different GPU model. A CUDA checkpoint carries device state built for one architecture's memory layout and capabilities, and no amount of driver compatibility makes an A100 replay what an L4 was doing.
const CheckImageDigest Check = "image-digest"
CheckImageDigest refuses a restore into image content other than what was captured. The reference is not compared: the same content is reachable under more than one, and a rebuilt or moved tag is one reference over two contents.
const CheckKernelMinimum Check = "kernel-minimum"
CheckKernelMinimum refuses a kernel too old to restore a modern glibc at all. glibc uses rseq, which needs 5.13 (criu#2229), and glibc 2.35 and newer segfault on restore below it (criu#2552).
const CheckKernelVersion Check = "kernel-version"
CheckKernelVersion refuses a restore onto a kernel other than the captured one. Restores that had worked for over a year have broken on a kernel upgrade alone: criu#2636.
const CheckLSMLabels Check = "lsm-labels"
CheckLSMLabels refuses a restore into a container with an AppArmor profile or SELinux label from a checkpoint whose dump recorded no labels. CRIU applies the target's label only to processes it recorded one for, so the workload would run unconfined. It sits outside the policy table, and the compatibility bypass does not waive it: skipping it would lift the Pod's security policy, not accept a riskier restore.
const CheckMIGSlice Check = "mig-slice"
CheckMIGSlice refuses a MIG slice at capture and at restore alike, because Snapshot supports whole GPUs only. It sits outside the policy table: it compares nothing against the other side, and it has to run ahead of GPU discovery, which fails on a slice under DRA and reports its parent card everywhere else.
const CheckMemoryLimit Check = "memory-limit"
CheckMemoryLimit refuses a restore into less memory than the checkpoint was captured with. Restoring faults the whole recorded address space back in, so a lower ceiling is not a slower restore but an OOM kill partway through one.
const CheckMount Check = "mount"
CheckMount refuses a restore into a pod that is missing a path the checkpoint had mounted. CRIU was told to leave those mounts alone and expect them to be there; where one is absent, the restored process gets a working directory or a dataset that simply is not there, and finds out by failing later.
type Environment ¶
type Environment struct {
KernelVersion string
CPUArch string
// /proc/cpuinfo flags. Only the instruction-set ones are compared.
CPUFeatures []string
Image string
ImageID string
CPULimit string
MemoryLimit string
DriverVersion string
GPUDevices []GPUDevice
ExternalizedMounts []string
// Resolved before comparing, so a comparison never touches disk.
ExistingMountPaths []string
}
Environment is one side of a comparison: the machine, pod, GPU and mount state a checkpoint was captured on, or the state a restore target offers. It carries no environment variables, deliberately: CRIU restores those with the process, so they are not something a node either offers or withholds.
Every field is optional. A field missing on either side is unknown rather than mismatched, because a checkpoint captured before it was ever recorded has to stay restorable. A producer that reads only some of these returns an Environment with those set and leaves its caller to fill in the rest.
type GPUInfo ¶
GPUInfo is the GPU part of an Environment, kept apart because discovery reads only this much of one.
type Gate ¶
type Gate string
Gate names the moment a comparison runs. The two gates see different state: only the later one can read the node's GPUs and the target's rootfs.
const ( // GatePreflight runs before the agent claims a restore attempt, where the // checkpoint manifest and the target pod are all that is readable. GatePreflight Gate = "preflight" // GateInspect runs once the placeholder container is resolved, where the // GPUs it sees and the mounts under its rootfs become readable. GateInspect Gate = "inspect" )
type IncompatibleError ¶
IncompatibleError reports a restore the target cannot run. It is terminal and distinct from every other restore error: no CRIU work was attempted, and retrying on this node cannot change the answer. Both gates raise it, so the caller reports one refusal whichever gate turned the restore down.
func NewIncompatibleError ¶
func NewIncompatibleError(gate Gate, mismatches []Mismatch) *IncompatibleError
func (*IncompatibleError) Error ¶
func (e *IncompatibleError) Error() string
type Mismatch ¶
Mismatch is one rule the target failed, carrying both compared values so the reported reason can name them.
func Compare ¶
func Compare(gate Gate, source, target Environment) []Mismatch
Compare reports every rule the target fails at the given gate. An empty result means the restore may proceed.