executor

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Nov 8, 2026 License: Apache-2.0 Imports: 30 Imported by: 0

Documentation

Overview

Package executor provides the top-level checkpoint and restore executors. These wire together the lib packages (criu, cuda, etc.) into multi-step workflows.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Checkpoint

Checkpoint captures a container through PageBroker and commits its artifact. The broker owns storage publication and, when supported, CUDA CustomStorage.

func CleanupFailure added in v0.3.0

func CleanupFailure(err error) error

CleanupFailure marks err as having come from cleanup rather than the capture.

func FetchArtifactManifest added in v0.3.0

func FetchArtifactManifest(ctx context.Context, controlSocketPath string, artifact *pagebroker.PublishedArtifact) (*types.CheckpointManifest, error)

FetchArtifactManifest reads a publication's manifest through PageBroker's metadata transaction, releasing it on every exit.

func IsCleanupFailure added in v0.3.0

func IsCleanupFailure(err error) bool

IsCleanupFailure reports whether err came from releasing a transaction rather than from the capture itself.

Types

type CheckpointRequest

type CheckpointRequest struct {
	ContainerID   string
	ContainerName string
	ContentUID    string
	StartedAt     time.Time
	NodeName      string
	PodName       string
	PodNamespace  string
	PodIP         string
	Clientset     kubernetes.Interface

	// StoreID binds this capture to a configured store; empty means legacy.
	StoreID string

	// Pod carries the image reference and limits the target container runs with, read from
	// the live pod by the caller rather than here: the capture path has no API
	// client for the pod, and the reconciler already holds it.
	Pod compat.Environment
	// CuInterposeRequested is the workload's explicit opt-in. Capture then fails unless
	// every CUDA process loaded the shim. Without it, a loaded shim is still captured.
	CuInterposeRequested bool
}

CheckpointRequest holds the content-owned inputs for a checkpoint operation.

type CleanupError

type CleanupError struct {
	Action  string `json:"action"`
	Message string `json:"message"`
}

CleanupError is the wire representation of a successful restore whose in-namespace cleanup did not fully complete.

func (*CleanupError) Error

func (e *CleanupError) Error() string

type RestoreCleanupError

type RestoreCleanupError struct {
	Err error
}

RestoreCleanupError reports a successful restore whose cleanup did not fully complete. The controller logs it, emits a warning event, and completes restore.

func NewRestoreCleanupError

func NewRestoreCleanupError(err error) *RestoreCleanupError

func (*RestoreCleanupError) Error

func (e *RestoreCleanupError) Error() string

func (*RestoreCleanupError) Unwrap

func (e *RestoreCleanupError) Unwrap() error

type RestoreInNamespaceResult

type RestoreInNamespaceResult struct {
	RestoredPID            int           `json:"restoredPID"`
	CleanupError           *CleanupError `json:"cleanupError,omitempty"`
	OverlayCaptureDuration time.Duration `json:"overlayCaptureDuration"`
	CRIUPrepareDuration    time.Duration `json:"criuPrepareDuration"`
	CRIURestoreDuration    time.Duration `json:"criuRestoreDuration"`
	CUDARestoreDuration    time.Duration `json:"cudaRestoreDuration"`
	// Error is set, with every other field empty, when nsrestore exits non-zero.
	// Step names the part of the in-namespace restore it came from, when known.
	Error string `json:"error,omitempty"`
	Step  string `json:"step,omitempty"`
}

func RestoreInNamespace

func RestoreInNamespace(ctx context.Context, opts RestoreOptions, log logr.Logger) (*RestoreInNamespaceResult, error)

RestoreInNamespace performs a full restore from inside the target container's namespaces.

type RestoreMounter

type RestoreMounter interface {
	MountBundle(ctx context.Context, pid int) (nsmount.MountPoint, error)
	MountCuInterpose(ctx context.Context, namespaceMount nsmount.MountPoint) (nsmount.MountPoint, error)
	MountArtifact(ctx context.Context, namespaceMount nsmount.MountPoint, artifactPath string) (nsmount.MountPoint, error)
	MountPageBroker(ctx context.Context, namespaceMount nsmount.MountPoint, stagingPath string) (nsmount.MountPoint, error)
}

RestoreMounter installs the fixed binary bundle, the cuinterpose libraries and one validated checkpoint artifact inside a placeholder container's mount namespace.

type RestoreOptions

type RestoreOptions struct {
	CustomStorageExecution *pagebroker.CustomStorageExecution
	HostProc               *os.File // Host proc remains accessible after CRIU changes mounts.
	CheckpointPath         string
	CUDADeviceMap          string
	GPUMountAliases        map[string]string
	CgroupRoot             string
	LSMProfile             string
	TargetPodIP            string
	// BundleDir is the path where the agent's binary bundle is mounted inside this namespace.
	BundleDir string
}

RestoreOptions holds configuration for an in-namespace restore.

type RestoreRequest

type RestoreRequest struct {
	ContentUID                  string
	BasePath                    string
	ContainerID                 string
	StartedAt                   time.Time
	PodName                     string
	PodNamespace                string
	TargetPodIP                 string
	ArtifactContainerName       string
	DestinationContainerName    string
	Clientset                   kubernetes.Interface
	CustomStorageAvailable      bool
	PageBrokerControlSocketPath string
	PageBrokerRestoreMode       string

	// PublishedArtifact, when set, switches restore to the artifact-addressed
	// RPCs; read from the content's recorded status, never reconstructed here.
	PublishedArtifact *pagebroker.PublishedArtifact

	// Decided by the caller, so both gates reach the same answer.
	SkipCompatCheck bool
	// WithoutProxy restores into a container whose PID 1 is its own command,
	// on a node without the restore proxy. Otherwise PID 1 must be the proxy.
	WithoutProxy bool
}

RestoreRequest holds the parameters for a restore operation.

type RestoreResult added in v0.2.0

type RestoreResult struct {
	// PlaceholderHostPID is the placeholder container's host PID, so callers
	// can reach into the container's mount namespace (e.g. to write sentinels
	// under /snapshot-control) without re-resolving via the runtime.
	PlaceholderHostPID int
	// RestoredPID is the restored process, relative to the container's PID
	// namespace.
	RestoredPID int
}

RestoreResult identifies the processes a successful restore leaves behind.

func Restore

func Restore(ctx context.Context, rt snapshotruntime.Runtime, log logr.Logger, req RestoreRequest, mounts RestoreMounter) (restored RestoreResult, retErr error)

Restore performs external restore for the given request. The DaemonSet side inspects the placeholder and launches nsrestore, which handles rootfs application, CRIU restore, and CUDA restore inside the namespace.

A RestoreCleanupError still carries the result: the restore itself succeeded.

type Step added in v0.3.0

type Step string

Step names the part of a checkpoint or restore flow a failure came from. It is rendered into conditions and events, logged as a structured key, and the troubleshooting guide is organised by it.

const (
	StepResolveArtifact       Step = "resolving checkpoint artifact"
	StepReadManifest          Step = "reading checkpoint manifest"
	StepValidateManifest      Step = "validating checkpoint manifest against the restore request"
	StepVerifyCuInterpose     Step = "verifying cuinterpose library identity"
	StepInspectPlaceholder    Step = "inspecting placeholder container"
	StepBuildGPUContext       Step = "building GPU context"
	StepMountBundle           Step = "mounting agent bundle into placeholder"
	StepMountCuInterpose      Step = "mounting cuinterpose into placeholder"
	StepPrepareRestore        Step = "preparing PageBroker restore"
	StepMountRestoreSource    Step = "mounting PageBroker restore source"
	StepRunNSRestore          Step = "running nsrestore"
	StepCheckStagedCheckpoint Step = "checking the staged checkpoint"
	StepPrepareCRIURestore    Step = "preparing CRIU restore"
	StepApplyRootfsDiff       Step = "applying rootfs diff"
	StepPrepareGPURestore     Step = "preparing GPU restore"
	StepRestoreCRIU           Step = "restoring with CRIU"
	StepRestoreCUDA           Step = "restoring CUDA state"
	StepCommitRestore         Step = "committing PageBroker restore"
	StepValidateRestored      Step = "validating restored process"
	StepCheckPostRestore      Step = "checking the post-restore action"
	StepPostRestore           Step = "running the post-restore action"

	StepResolveCheckpointPath Step = "resolving checkpoint artifact path"
	StepInspectSource         Step = "inspecting source container"
	StepPrepareCheckpoint     Step = "preparing PageBroker checkpoint"
	StepInspectCuInterpose    Step = "inspecting cuinterpose"
	StepStageCUDAJobFile      Step = "staging CUDA job file"
	StepConfigureCheckpoint   Step = "configuring CRIU dump and writing checkpoint manifest"
	StepCheckpointGPU         Step = "checkpointing GPU state"
	StepDumpCRIU              Step = "dumping with CRIU"
	StepCaptureOverlay        Step = "capturing rootfs diff"
	StepCommitCheckpoint      Step = "committing PageBroker checkpoint"
)

func StepOf added in v0.3.0

func StepOf(err error) Step

StepOf returns the step a failure came from, or "" when it carries none.

type StepError added in v0.3.0

type StepError struct {
	Step Step
	Err  error
}

StepError carries the step a failure came from. Unwrap keeps the cause visible to errors.Is and errors.As.

func (*StepError) Error added in v0.3.0

func (e *StepError) Error() string

func (*StepError) Unwrap added in v0.3.0

func (e *StepError) Unwrap() error

type SuspendedSource added in v0.3.0

type SuspendedSource struct {
	// GPUPIDs are the GPU processes the capture found, to be handed their GPUs back.
	GPUPIDs []int

	// CuInterposePrepared reports that the capture removed the tree's shared GPU mappings.
	// Nothing puts them back, so a source in that state can only be terminated.
	CuInterposePrepared bool

	// CustomStorageUsed reports that the GPU memory went to PageBroker rather than staying
	// with the driver. That execution is torn down before recovery runs, so an in-place
	// restore has nothing to restore from and the source can only be terminated.
	CustomStorageUsed bool
}

SuspendedSource describes what a failed capture left behind, so the caller can decide whether the workload can be put back.

func SuspendedSourceOf added in v0.3.0

func SuspendedSourceOf(err error) (SuspendedSource, bool)

SuspendedSourceOf returns what a failed capture left behind, and whether the failure left the source needing recovery at all.

Jump to

Keyboard shortcuts

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