Documentation
¶
Overview ¶
Package podcontract defines Snapshot's workload Pod contract and provides helpers to build, validate, and interpret restore Pods.
Index ¶
- Constants
- func Build(pod *corev1.Pod, request Request, options Options) (*corev1.Pod, error)
- func CuInterposeLauncherPrefix() []string
- func FormatRestoreComplete(rc RestoreComplete) []byte
- func GetRestoreFromSnapshotName(annotations map[string]string) (string, error)
- func IsReservedControlFile(name string) bool
- func NonTargetArtifactContainers(annotations map[string]string) ([]string, error)
- func NonTargetArtifactSubdir(uid string) (string, error)
- func ParseCuInterposeAnnotation(annotations map[string]string) (bool, error)
- func SkipCompatCheckFromAnnotations(annotations map[string]string) bool
- func Validate(pod *corev1.Pod, request Request) error
- func ValidateContainerMappings(mappings []ContainerMapping, capturedSource string) error
- func ValidateCuInterposeLauncher(container *corev1.Container) error
- type ContainerMapping
- type Options
- type Request
- type RestoreComplete
- type RestoreOutcome
Constants ¶
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" )
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" )
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.
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.
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 ¶
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 ¶
GetRestoreFromSnapshotName returns the same-namespace PodSnapshot named by the restore-from annotation.
func IsReservedControlFile ¶ added in v0.3.0
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
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
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
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
SkipCompatCheckFromAnnotations reports whether compatibility checks are disabled.
func Validate ¶
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
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 ¶
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.