podcontract

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: 9 Imported by: 0

Documentation

Overview

Package podcontract defines Snapshot's workload Pod contract and provides helpers to build, validate, and interpret restore Pods.

Index

Constants

View Source
const (
	// CuInterposeMountPath is where an opted-in target container sees the
	// cuinterpose libraries and launcher. Restore mounts the agent's matching
	// copies, verified against the checkpoint's library hashes, at the same path.
	CuInterposeMountPath = "/tmp/snapshot-cuda"

	// CuInterposeLibraryPath is the frontend library the launcher preloads.
	CuInterposeLibraryPath = CuInterposeMountPath + "/libcuinterpose.so"

	// CuInterposeLauncherPath is the launcher that starts the workload with the
	// frontend library preloaded.
	CuInterposeLauncherPath = CuInterposeMountPath + "/cuinterpose-launch"
)
View Source
const (
	// NonTargetArtifactContainersAnnotation opts named, regular non-target source
	// containers into SnapshotJob-owned non-target artifact storage. The caller
	// mounts the same shared PVC used by Snapshot artifact maintenance.
	NonTargetArtifactContainersAnnotation = "nvidia.com/snapshot-non-target-artifact-containers"
	// SnapshotJobUIDEnv identifies one immutable checkpoint attempt.
	SnapshotJobUIDEnv = "SNAPSHOT_JOB_UID"
	// NonTargetArtifactSubdirEnv names the attempt's directory relative to the
	// shared PVC root, allowing non-target containers and maintenance to use different mounts.
	NonTargetArtifactSubdirEnv  = "SNAPSHOT_NON_TARGET_ARTIFACT_SUBDIR"
	NonTargetArtifactsDirectory = "non-target-artifacts"
)
View Source
const (
	// RestoreFromAnnotation names the PodSnapshot to restore in the Pod's
	// namespace.
	RestoreFromAnnotation = "nvidia.com/restore-from"

	// RestoreContainerMapAnnotation optionally maps the single captured source
	// container to one or more restore destinations. Its value is a
	// comma-separated list of source=destination pairs. When absent, restore
	// uses the captured container name as the destination.
	RestoreContainerMapAnnotation = "nvidia.com/restore-container-map"

	// SkipCompatCheckAnnotation disables compatibility checks for one restore.
	SkipCompatCheckAnnotation = "nvidia.com/snapshot-skip-compat-check"

	// CuInterposeAnnotation enables multi-GPU support, which runs checkpoint
	// targets under the CUDA interposer.
	CuInterposeAnnotation = "nvidia.com/snapshot-multi-gpu"

	// DefaultSeccompLocalhostProfile is the kubelet-local profile installed by
	// the Snapshot Helm chart to block io_uring for CRIU.
	DefaultSeccompLocalhostProfile = "profiles/block-iouring.json"

	// SnapshotControlVolumeName is the per-Pod emptyDir used to carry capture and
	// restore lifecycle files between Snapshot and the workload.
	SnapshotControlVolumeName = "snapshot-control"

	// SnapshotControlMountPath is where the control volume is mounted inside a
	// Snapshot-managed workload container.
	SnapshotControlMountPath = "/snapshot-control"

	// SnapshotControlDirEnv is the canonical environment variable exposing the
	// control mount path to the workload.
	SnapshotControlDirEnv = "SNAPSHOT_CONTROL_DIR"

	// LegacySnapshotControlDirEnv is the deprecated environment variable
	// exposing the control mount path to the workload.
	//
	// Deprecated: use SnapshotControlDirEnv instead.
	LegacySnapshotControlDirEnv = "DYN_SNAPSHOT_CONTROL_DIR"

	// ReadyForSnapshotFile is written by the workload when the model is loaded
	// and the workload is ready for capture. The source Pod's kubelet readiness
	// probe observes it through the control volume.
	ReadyForSnapshotFile = "ready-for-snapshot"

	// CUDAJobFileName is the stable name under which the
	// cuda-checkpoint-helper launch-job wrapper persists the CUDA checkpoint job
	// file inside the control volume.
	CUDAJobFileName = "cuda-checkpoint-job"

	// CUDAJobFilePath is the full stable path to the persisted CUDA checkpoint
	// job file.
	CUDAJobFilePath = SnapshotControlMountPath + "/" + CUDAJobFileName

	// RestoreStandbyModeEnv asked standby-aware workload entrypoints to remain
	// inert until Snapshot replaced them with restored processes. Snapshot
	// published the name but never injected it.
	//
	// Deprecated: Snapshot now replaces a restore container's command with
	// RestoreProxyPath, so the entrypoint never runs and nothing needs to stay
	// inert. Restore Pods can keep the source's command.
	RestoreStandbyModeEnv = "SNAPSHOT_RESTORE_STANDBY"

	// LegacyRestoreStandbyModeEnv is the previous name of RestoreStandbyModeEnv,
	// kept for existing workload integrations that still read it. Snapshot
	// publishes the name but does not inject it.
	//
	// Deprecated: see RestoreStandbyModeEnv. This alias is removed in the next
	// release.
	LegacyRestoreStandbyModeEnv = "DYN_SNAPSHOT_RESTORE_STANDBY"

	// RestoreCompleteFile is written by the Snapshot agent when restore has
	// completed and the workload may resume. Its contents are key=value lines
	// built by FormatRestoreComplete; workloads that only gate on the file's
	// existence may ignore them.
	RestoreCompleteFile = "restore-complete"

	// RestoreFailedFile is written by the Snapshot agent before it kills a
	// destination container whose restore failed. The failing container never
	// acts on it; a later container in the same Pod reads it as proof that the
	// Pod's one restore was already used.
	RestoreFailedFile = "restore-failed"

	// RestoreCompletePIDKey names the restored process's PID, relative to the
	// destination container's PID namespace, in RestoreCompleteFile.
	RestoreCompletePIDKey = "pid"

	// RestoreProxyBinaryName is the PID 1 process Snapshot runs in restore
	// destination containers. It waits for RestoreCompleteFile, then follows
	// the restored process and exits with its status.
	RestoreProxyBinaryName = "snapshot-restore-proxy"

	// RestoreProxyPath is the proxy as the container sees it, in the control
	// volume. It is the whole command of a restore destination container.
	RestoreProxyPath = SnapshotControlMountPath + "/" + RestoreProxyBinaryName
)

Snapshot workload Pod annotations and control protocol.

View Source
const (
	// RestoreNotRepeatableExitCode means this Pod's one restore is spent: the
	// proxy found RestoreCompleteFile or RestoreFailedFile at start, left by an
	// earlier container, or RestoreFailedFile appeared while it waited.
	RestoreNotRepeatableExitCode = 112

	// RestoreProxyErrorExitCode means the proxy could not follow the restored
	// process, for example because RestoreCompleteFile was malformed or the
	// restored PID was not its child.
	RestoreProxyErrorExitCode = 113
)

Exit codes reserved by the restore proxy. Every other code is the restored workload's own, or 128 plus the signal number that killed it.

View Source
const (
	// RestoredCondition is the Pod status condition owned by the Snapshot node
	// agent.
	RestoredCondition = "nvidia.com/Restored"

	// RestoreReasonInProgress marks active restore execution.
	RestoreReasonInProgress = "RestoreInProgress"
	// RestoreReasonSucceeded marks a terminal all-destinations success.
	RestoreReasonSucceeded = "RestoreSucceeded"
	// RestoreReasonFailed marks a terminal all-destinations failure.
	RestoreReasonFailed = "RestoreFailed"
	// RestoreReasonPartiallySucceeded marks a terminal mixed destination outcome.
	RestoreReasonPartiallySucceeded = "RestorePartiallySucceeded"
	// RestoreReasonIncompatible marks a restore refused before CRIU.
	RestoreReasonIncompatible = "RestoreIncompatible"
)

Stable reasons used on the nvidia.com/Restored Pod condition. Dependency-wait reasons remain agent-internal; consumers should use ClassifyRestoreOutcome.

Variables

This section is empty.

Functions

func Build

func Build(pod *corev1.Pod, request Request, options Options) (*corev1.Pod, error)

Build returns a restore-shaped deep copy of pod. The caller's Pod is never mutated, including when validation fails. Container commands stay as the caller set them: the node agent replaces them when it restores. Mapping sources must come from the referenced PodSnapshot; this pure builder performs no API read to derive them.

func CuInterposeLauncherPrefix added in v0.2.0

func CuInterposeLauncherPrefix() []string

CuInterposeLauncherPrefix starts a target command under the launcher. SnapshotJob adds it to opted-in sources, and ordinary Pods must add it themselves.

func FormatRestoreComplete added in v0.2.0

func FormatRestoreComplete(rc RestoreComplete) []byte

FormatRestoreComplete renders the content of RestoreCompleteFile.

func GetRestoreFromSnapshotName

func GetRestoreFromSnapshotName(annotations map[string]string) (string, error)

GetRestoreFromSnapshotName returns the same-namespace PodSnapshot named by the restore-from annotation.

func IsReservedControlFile added in v0.3.0

func IsReservedControlFile(name string) bool

IsReservedControlFile reports whether name is a file that Snapshot or its helpers write in the snapshot-control volume. A workload's post-restore file action must not name one: writing it would act as Snapshot's own signal.

func NonTargetArtifactContainers added in v0.3.0

func NonTargetArtifactContainers(annotations map[string]string) ([]string, error)

NonTargetArtifactContainers parses the opt-in annotation. Container membership and exclusion of the capture target are checked against the source Pod.

func NonTargetArtifactSubdir added in v0.3.0

func NonTargetArtifactSubdir(uid string) (string, error)

NonTargetArtifactSubdir returns the directory owned by one SnapshotJob attempt. A UID is validated before it is allowed to become a filesystem path element.

func ParseCuInterposeAnnotation added in v0.2.0

func ParseCuInterposeAnnotation(annotations map[string]string) (bool, error)

ParseCuInterposeAnnotation accepts enabled or disabled after trimming whitespace. An absent annotation leaves support disabled; other present values are invalid.

func SkipCompatCheckFromAnnotations added in v0.2.0

func SkipCompatCheckFromAnnotations(annotations map[string]string) bool

SkipCompatCheckFromAnnotations reports whether compatibility checks are disabled.

func Validate

func Validate(pod *corev1.Pod, request Request) error

Validate verifies that pod implements Snapshot's minimum restore protocol. Optional workload policy such as startup gating and seccomp selection is not part of this agent-facing validation. Validate performs no API reads and never mutates the Pod.

func ValidateContainerMappings

func ValidateContainerMappings(mappings []ContainerMapping, capturedSource string) error

ValidateContainerMappings enforces the one-source-to-many-destinations contract after parsing.

func ValidateCuInterposeLauncher added in v0.2.0

func ValidateCuInterposeLauncher(container *corev1.Container) error

ValidateCuInterposeLauncher checks that an opted-in container's command starts with the launcher prefix and that a workload follows in command or args.

Types

type ContainerMapping

type ContainerMapping struct {
	Source      string
	Destination string
}

ContainerMapping maps the one captured source container to a restore destination in the target Pod.

func ContainerMappingsFromAnnotations

func ContainerMappingsFromAnnotations(
	annotations map[string]string,
	capturedSource string,
) ([]ContainerMapping, error)

ContainerMappingsFromAnnotations parses the optional flat restore mapping. Absence keeps the existing same-name restore behavior.

type Options

type Options struct {
	// SeccompProfile is the kubelet-local profile applied to each restore
	// destination container. Empty leaves seccomp configuration entirely
	// caller-owned.
	SeccompProfile string

	// EnableStartupGate replaces each destination container's startup probe
	// with a restore-completion gate. Workload owners opt in when Kubernetes
	// must withhold readiness and liveness until restore completes.
	EnableStartupGate bool
}

Options controls optional restore Pod shaping. Its zero value applies only the mechanics required by Snapshot's minimum restore protocol.

type Request

type Request struct {
	SnapshotName    string
	SourceContainer string
	Mappings        []ContainerMapping
}

Request identifies the PodSnapshot source and its restore destinations. Empty Mappings default to restoring SourceContainer into a same-named destination container.

type RestoreComplete added in v0.2.0

type RestoreComplete struct {
	// PID is the restored process, relative to the destination container's
	// PID namespace.
	PID int
}

RestoreComplete is the content of RestoreCompleteFile.

func ParseRestoreComplete added in v0.2.0

func ParseRestoreComplete(data []byte) (RestoreComplete, error)

ParseRestoreComplete reads the content of RestoreCompleteFile. Unknown keys are ignored so the agent can add fields without breaking older readers.

type RestoreOutcome

type RestoreOutcome string

RestoreOutcome is the stable, consumer-facing state of a restore request.

const (
	// RestoreOutcomeUnknown means the Restored condition exists but cannot be
	// classified safely by this API version.
	RestoreOutcomeUnknown RestoreOutcome = "Unknown"
	// RestoreOutcomePending means restore has not reached a terminal outcome.
	// It includes an absent condition and active restore execution.
	RestoreOutcomePending RestoreOutcome = "Pending"
	// RestoreOutcomeSucceeded means every requested destination was restored.
	RestoreOutcomeSucceeded RestoreOutcome = "Succeeded"
	// RestoreOutcomeFailed means no requested destination was restored.
	RestoreOutcomeFailed RestoreOutcome = "Failed"
	// RestoreOutcomePartiallySucceeded means some, but not all, requested
	// destinations were restored.
	RestoreOutcomePartiallySucceeded RestoreOutcome = "PartiallySucceeded"
)

func ClassifyRestoreOutcome

func ClassifyRestoreOutcome(conditions []corev1.PodCondition) RestoreOutcome

ClassifyRestoreOutcome returns the public restore outcome represented by Pod conditions. A missing Restored condition is Pending. An unrecognized status or reason is Unknown so callers can apply their own version-skew policy.

func (RestoreOutcome) Terminal

func (o RestoreOutcome) Terminal() bool

Terminal reports whether the restore outcome is final.

Jump to

Keyboard shortcuts

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