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 ¶
- func Checkpoint(ctx context.Context, rt snapshotruntime.Runtime, log logr.Logger, ...) (*pagebroker.PublishedArtifact, error)
- func CleanupFailure(err error) error
- func FetchArtifactManifest(ctx context.Context, controlSocketPath string, ...) (*types.CheckpointManifest, error)
- func IsCleanupFailure(err error) bool
- type CheckpointRequest
- type CleanupError
- type RestoreCleanupError
- type RestoreInNamespaceResult
- type RestoreMounter
- type RestoreOptions
- type RestoreRequest
- type RestoreResult
- type Step
- type StepError
- type SuspendedSource
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Checkpoint ¶
func Checkpoint(ctx context.Context, rt snapshotruntime.Runtime, log logr.Logger, req CheckpointRequest, cfg *types.AgentConfig) (*pagebroker.PublishedArtifact, error)
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
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
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 ¶
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" )
type StepError ¶ added in v0.3.0
StepError carries the step a failure came from. Unwrap keeps the cause visible to errors.Is and errors.As.
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.