Documentation
¶
Overview ¶
Package runtime provides low-level host and container-runtime primitives for snapshot execution.
Index ¶
- Constants
- func ApplyDeletedFiles(checkpointPath, targetRoot string, log logr.Logger) error
- func ApplyRootfsDiff(checkpointPath, targetRoot, bundleDir string, log logr.Logger) error
- func BuildMountPolicy(mounts []types.MountInfo, rootFS string, maskedPaths []string) (map[string]string, []string)
- func CaptureDeletedFiles(upperDir, checkpointDir string) (bool, error)
- func CaptureRootfsDiff(upperDir, checkpointDir string, exclusions types.OverlaySettings, ...) (string, error)
- func CheckProcessHandles(files []*os.File) error
- func ClassifyMounts(mounts []types.MountInfo, ociSpec *specs.Spec, rootFS string) []types.MountInfo
- func CommandInNamespaces(ctx context.Context, pid int, mountNS *os.File, rootPath, binaryPath string) (*exec.Cmd, func(), error)
- func ControlSentinelExists(hostPID int, name string) (bool, error)
- func GetNetNSInode(pid int) (uint64, error)
- func GetOverlayUpperDir(pid int) (string, error)
- func GetRootFS(pid int) (string, error)
- func InheritFile(cmd *exec.Cmd, file *os.File) string
- func OpenProcessHandles(pids []int) ([]*os.File, error)
- func ParseProcExitCode(statLine string) (syscall.WaitStatus, error)
- func ProcessTreePIDs(rootPID int) []int
- func ReadKernelVersion(hostProcPath string) (string, error)
- func ReadMountInfo(pid int) ([]types.MountInfo, error)
- func ReadProcessFilesystemIDs(procRoot string, pid int) (int, int, error)
- func RemountProcSys(rw bool) error
- func RemoveControlSentinel(dir, name string) error
- func ResolveCgroupRootFromHostPID(pid int) (string, error)
- func ResolveHostPIDs(hostProcRoot, procRoot string, pids []int) ([]int, error)
- func ResolveManifestPIDsToObservedPIDs(processes []ProcessDetails, restoredPID int, manifestPIDs []int) ([]int, error)
- func SendSignalToPID(log logr.Logger, pid int, sig syscall.Signal, reason string) error
- func SetProcessGroupCancellation(cmd *exec.Cmd, waitDelay time.Duration)
- func StripCRIScheme(id string) string
- func ValidateProcessState(procRoot string, pid int) error
- func WriteControlSentinel(hostPID int, name string, contents []byte) error
- type CRIORuntime
- func (r *CRIORuntime) Close() error
- func (r *CRIORuntime) ResolveContainer(ctx context.Context, id string) (int, *specs.Spec, error)
- func (r *CRIORuntime) ResolveContainerByPod(ctx context.Context, podName, podNamespace, containerName string) (int, *specs.Spec, error)
- func (r *CRIORuntime) ResolveContainerIDByPod(ctx context.Context, podName, podNamespace, containerName string) (string, error)
- func (r *CRIORuntime) ResolveContainerImageID(ctx context.Context, containerID string) (string, error)
- func (r *CRIORuntime) TerminateContainer(ctx context.Context, containerID string) error
- type ContainerdRuntime
- func (r *ContainerdRuntime) Close() error
- func (r *ContainerdRuntime) ResolveContainer(ctx context.Context, containerID string) (int, *specs.Spec, error)
- func (r *ContainerdRuntime) ResolveContainerByPod(ctx context.Context, podName, podNamespace, containerName string) (int, *specs.Spec, error)
- func (r *ContainerdRuntime) ResolveContainerIDByPod(ctx context.Context, podName, podNamespace, containerName string) (string, error)
- func (r *ContainerdRuntime) ResolveContainerImageID(ctx context.Context, containerID string) (string, error)
- func (r *ContainerdRuntime) TerminateContainer(ctx context.Context, containerID string) error
- type ProcessDetails
- type Runtime
Constants ¶
const ( ContainerdSocket = "/run/containerd/containerd.sock" CRIOSocket = "/var/run/crio/crio.sock" RuntimeContainerd = "containerd" RuntimeCRIO = "crio" )
Default socket paths and runtime-type identifiers.
const HostCgroupPath = "/sys/fs/cgroup"
const HostProcPath = "/host/proc"
HostProcPath is the mount point for the host's /proc in DaemonSet pods.
Variables ¶
This section is empty.
Functions ¶
func ApplyDeletedFiles ¶
ApplyDeletedFiles removes files marked as deleted in the checkpoint.
func ApplyRootfsDiff ¶
ApplyRootfsDiff extracts rootfs-diff.tar into the target root.
The archive is copied to local disk first. tar walks members with many small reads; doing that directly from NFS is much slower than one sequential copy plus a local extract.
func BuildMountPolicy ¶
func BuildMountPolicy(mounts []types.MountInfo, rootFS string, maskedPaths []string) (map[string]string, []string)
BuildMountPolicy classifies mounts and masked paths for CRIU dump. Mounts must already have IsOCIManaged set by ClassifyMounts.
Policy (evaluated top to bottom):
- Skip: non-OCI /proc/*, /sys/*, /run/* submounts (virtual/runtime, not in placeholder)
- Native: /dev/shm tmpfs (CRIU saves and restores content)
- Masked: OCI masked non-directory paths that exist under rootFS → /dev/null
- Externalize: everything else (OCI mounts the runtime recreates in placeholder)
func CaptureDeletedFiles ¶
CaptureDeletedFiles finds whiteout files and saves them to a JSON file.
func CaptureRootfsDiff ¶
func CaptureRootfsDiff(upperDir, checkpointDir string, exclusions types.OverlaySettings, bindMountDests []string) (string, error)
CaptureRootfsDiff captures the overlay upperdir to a tar file.
The archive is written to a temporary file first and renamed atomically on success, so a partial or failed capture never leaves a corrupt archive at the final path.
func CheckProcessHandles ¶ added in v0.2.0
CheckProcessHandles rejects targets that exited while their host PIDs were resolved.
func ClassifyMounts ¶
ClassifyMounts sets IsOCIManaged on each mount by matching against the container's OCI spec (mounts, masked paths, readonly paths). Handles /run/ ↔ /var/run/ aliasing since some images symlink one to the other.
func CommandInNamespaces ¶ added in v0.2.0
func CommandInNamespaces(ctx context.Context, pid int, mountNS *os.File, rootPath, binaryPath string) (*exec.Cmd, func(), error)
CommandInNamespaces runs a host binary in the container's namespaces and root. mountNS keeps the mount namespace available if its original process exits, but the other namespaces still use pid and require that process to stay alive until entry. The caller retains ownership of mountNS and must call closeFiles after the command finishes to release the binary and root descriptors opened here.
func ControlSentinelExists ¶
ControlSentinelExists reports whether a sentinel exists in the workload container's snapshot-control volume. It returns an error when the container's control mount cannot be inspected, so callers do not mistake an inaccessible volume for a missing sentinel.
func GetNetNSInode ¶
GetNetNSInode returns the network namespace inode for a container process via /host/proc.
func GetOverlayUpperDir ¶
GetOverlayUpperDir extracts the overlay upperdir from mountinfo.
func InheritFile ¶ added in v0.2.0
InheritFile passes file to cmd's child as an extra descriptor and returns the /proc/self/fd path that refers to it there. The caller retains file ownership.
func OpenProcessHandles ¶ added in v0.2.0
OpenProcessHandles opens pidfds in the caller's PID namespace. The caller must keep them open through host PID resolution and request submission.
func ParseProcExitCode ¶
func ParseProcExitCode(statLine string) (syscall.WaitStatus, error)
ParseProcExitCode extracts and decodes the exit_code field (field 52) from a /proc/<pid>/stat line.
func ProcessTreePIDs ¶
ProcessTreePIDs walks the process tree rooted at rootPID and returns all PIDs. Used during checkpoint to enumerate the source process tree before CUDA filtering.
func ReadKernelVersion ¶ added in v0.2.0
ReadKernelVersion reads the host's /proc/sys/kernel/osrelease entry documented at https://man7.org/linux/man-pages/man5/proc_sys_kernel.5.html.
func ReadMountInfo ¶
ReadMountInfo reads and parses mountinfo for a container process via /host/proc.
func ReadProcessFilesystemIDs ¶
ReadProcessFilesystemIDs returns the filesystem UID and GID from a proc status entry.
func RemountProcSys ¶
RemountProcSys remounts /proc/sys read-write or read-only.
func RemoveControlSentinel ¶
RemoveControlSentinel removes a sentinel from the snapshot-control mount at dir. The directory must exist: a missing file is already removed, but a missing mount is an error so callers do not confuse "cannot see the volume" with "volume is clean".
func ResolveCgroupRootFromHostPID ¶
ResolveCgroupRootFromHostPID reads the unified cgroup v2 path for a PID via /host/proc.
func ResolveHostPIDs ¶ added in v0.2.0
ResolveHostPIDs maps PIDs observed through procRoot to the host proc view. Match the process's own namespace because CRIU can restore it below nsrestore.
func ResolveManifestPIDsToObservedPIDs ¶
func ResolveManifestPIDsToObservedPIDs(processes []ProcessDetails, restoredPID int, manifestPIDs []int) ([]int, error)
ResolveManifestPIDsToObservedPIDs is the restore-side remap from checkpoint-time innermost namespace PIDs onto the current observed PIDs in the restored subtree rooted at restoredPID.
func SendSignalToPID ¶
SendSignalToPID sends a signal to a host-visible PID via syscall.Kill.
func SetProcessGroupCancellation ¶ added in v0.2.0
SetProcessGroupCancellation makes cancellation kill a helper and its children, including children that keep the command's output pipes open. After the kill, Wait returns once waitDelay passes even if descendants still hold those pipes.
func StripCRIScheme ¶
StripCRIScheme trims the kubelet-format scheme prefix from a ContainerStatus.ContainerID. Returns id unchanged if no known scheme matches.
func ValidateProcessState ¶
ValidateProcessState checks that a process is alive and not a zombie.
func WriteControlSentinel ¶
WriteControlSentinel writes a sentinel file into the workload container's snapshot-control volume at SnapshotControlMountPath/<name>, accessed through the agent's /host/proc/<pid>/root view of the container's mount namespace.
hostPID must be a PID inside the container's mount namespace (the container task PID is the canonical choice). The sentinel is observed by the workload via inotify on the control directory; it replaces the SIGUSR1/SIGCONT agent-to-workload signals that previously required the workload to run as PID 1.
The write uses create-then-rename so the workload never observes a partial file.
Types ¶
type CRIORuntime ¶
type CRIORuntime struct {
// contains filtered or unexported fields
}
CRIORuntime resolves container identity via the CRI-O CRI gRPC socket.
func NewCRIORuntime ¶
func NewCRIORuntime(socket string) (*CRIORuntime, error)
func (*CRIORuntime) Close ¶
func (r *CRIORuntime) Close() error
func (*CRIORuntime) ResolveContainer ¶
func (*CRIORuntime) ResolveContainerByPod ¶
func (r *CRIORuntime) ResolveContainerByPod(ctx context.Context, podName, podNamespace, containerName string) (int, *specs.Spec, error)
ResolveContainerByPod picks the first RUNNING container matching the pod + container-name label filter; errors if none qualify.
func (*CRIORuntime) ResolveContainerIDByPod ¶
func (*CRIORuntime) ResolveContainerImageID ¶ added in v0.2.0
func (*CRIORuntime) TerminateContainer ¶ added in v0.2.0
func (r *CRIORuntime) TerminateContainer(ctx context.Context, containerID string) error
type ContainerdRuntime ¶
type ContainerdRuntime struct {
// contains filtered or unexported fields
}
func NewContainerdRuntime ¶
func NewContainerdRuntime(socket string) (*ContainerdRuntime, error)
func (*ContainerdRuntime) Close ¶
func (r *ContainerdRuntime) Close() error
func (*ContainerdRuntime) ResolveContainer ¶
func (*ContainerdRuntime) ResolveContainerByPod ¶
func (*ContainerdRuntime) ResolveContainerIDByPod ¶
func (*ContainerdRuntime) ResolveContainerImageID ¶ added in v0.2.0
func (*ContainerdRuntime) TerminateContainer ¶ added in v0.2.0
func (r *ContainerdRuntime) TerminateContainer(ctx context.Context, containerID string) error
type ProcessDetails ¶
type ProcessDetails struct {
ObservedPID int
ParentPID int
OutermostPID int
InnermostPID int
NamespacePIDs []int
Cmdline string
}
ProcessDetails captures the parent link plus the observed, outermost, and innermost PID views for one proc entry. ObservedPID is relative to the proc root being read.
func ReadProcessDetails ¶
func ReadProcessDetails(procRoot string, pid int) (ProcessDetails, error)
ReadProcessDetails reads one proc entry from a proc root.
func ReadProcessDetailsOrDefault ¶
func ReadProcessDetailsOrDefault(procRoot string, pid int) ProcessDetails
ReadProcessDetailsOrDefault preserves pid-scoped logging even when proc parsing fails.
func ReadProcessTable ¶
func ReadProcessTable(procRoot string) ([]ProcessDetails, error)
ReadProcessTable snapshots every numeric proc entry under procRoot. Used by restore-side PID remap and diagnostics after CRIU restore.
type Runtime ¶
type Runtime interface {
ResolveContainer(ctx context.Context, id string) (int, *specs.Spec, error)
ResolveContainerIDByPod(ctx context.Context, pod, ns, ctr string) (string, error)
ResolveContainerByPod(ctx context.Context, pod, ns, ctr string) (int, *specs.Spec, error)
ResolveContainerImageID(ctx context.Context, id string) (string, error)
// TerminateContainer requests zero-grace termination through CRI using the
// runtime container ID. Implementations validate any supplied runtime scheme
// before dispatch.
TerminateContainer(ctx context.Context, id string) error
Close() error
}
Runtime abstracts the container-identity APIs behind a two-backend switch. Resolve methods return non-nil *specs.Spec with PID > 0 on success, or an error.