CRD Reference

PodMotion ships five Custom Resource Definitions (CRDs). All are in the migration.podmotion.io/v1alpha1 API group. The primary interface is the PodMigration CR — there is no kubectl plugin in v0.1.0-alpha.

PodMigration

The primary migration trigger. Create a PodMigration CR to initiate a pod migration. The source pod is never deleted before the mode-appropriate verification condition is True — guaranteed by design (TrafficVerified / ADR-0012 outside Strict mode, ServiceContinuityVerified / ADR-0352 under Strict; verification modes defined in ADR-0055).

Group / Version / Kind: migration.podmotion.io/v1alpha1 / PodMigration

Minimal example

apiVersion: migration.podmotion.io/v1alpha1
kind: PodMigration
metadata:
  name: migrate-my-pod
spec:
  podName: my-pod
  podNamespace: default
  targetNodeName: worker-2        # optional: pin destination node
  tcpPreservationMode: Strict     # optional: None (default) | Strict | BestEffort

Spec fields

Field	Type	Required	Default	Description
`podName`	string	yes	—	Name of the source pod to migrate.
`podNamespace`	string	yes	—	Namespace of the source pod.
`targetNodeName`	string	no	—	User-supplied destination node pin. When omitted, the scheduler selects the destination node automatically.
`tcpPreservationMode`	enum	no	`None`	TCP connection preservation mode. `None` (default) performs no TCP state transfer. `Strict` opts in to full TCP preservation via the eBPF relay. `BestEffort` attempts preservation but does not abort on failure.
`mode`	enum	no	`PreCopy`	Migration memory transfer strategy. `PreCopy` (default) iteratively copies dirty pages before freeze. `PostCopy` restores immediately then pulls faulted pages on demand (requires `CONFIG_USERFAULTFD=y`, kernel 5.15+).
`dryRun`	bool	no	`false`	When `true`, the controller validates the migration plan and reports what would happen without executing it. Recommended entry point for evaluators.
`rollbackOnFailure`	bool	no	`true`	When `true`, the controller rolls back to the source pod state on any terminal error.
`completionTimeoutSeconds`	int	no	`600`	Maximum seconds allowed for the full migration. The migration fails with `DeadlineExceeded` if not complete within this window.
`freezeWindowBudgetMs`	int	no	`500`	Maximum milliseconds the source pod may be frozen during checkpoint. Exceeding this budget causes the migration to abort before freeze.
`preCopyMaxRounds`	int	no	`5`	Maximum number of iterative memory pre-copy rounds before the controller proceeds to final freeze-and-checkpoint.
`destinationNode`	string	—	—	Controller-written. The scheduler writes the selected destination node name into this field during planning. This field is not authored by users; setting it manually has no effect.

Migration phases — MigrationPhase state machine

PodMotion's migration state machine is defined by 22 phase constants (MigrationPhase, validated by the CRD enum). For TCP-preserving migrations (tcpPreservationMode=Strict|BestEffort) the operator runs the 12-phase TCP-first pipeline introduced in ADR-0047; stateless migrations (tcpPreservationMode=None) skip SocketInventory and TCPVerifying and traverse the legacy short pipeline. The list below is a representative subset of the primary migration path, not the complete state machine — consult the installed CRD manifest for the full MigrationPhase enum.

Illustrative primary-path subset:

Pending → Validating → PreCopyMemory → FinalFreezeStateCapture
        → TCPVerifying → ServiceVerifying → CutoverComplete → Complete

Error path:
  (any phase) → Failed → RollingBack

The CRD schema defines 14 condition types. These are the canonical 14:

Condition Type	Description
`Scheduled`	Migration has been accepted and scheduled by the controller.
`NodeSelected`	Destination node has been selected by the scheduler.
`PolicyChecked`	Applicable MigrationPolicy objects have been evaluated.
`Validating`	Source pod and destination node constraints are being validated.
`PreCopyStarted`	Iterative pre-copy memory rounds have begun (PreCopy mode).
`Checkpointing`	Source pod freeze and CRIU checkpoint capture is in progress.
`CheckpointComplete`	CRIU checkpoint has been captured successfully.
`Transferring`	Checkpoint image is being transferred to the destination node.
`TransferComplete`	Checkpoint image transfer to the destination node is complete.
`Restoring`	Pod is being restored from checkpoint on the destination node.
`RestoreComplete`	Pod has been successfully restored on the destination node.
`TrafficVerified`	Application probe succeeded and TCP flow ownership has been transferred. Outside `Strict` mode, source pod is eligible for deletion only after this condition is `True`.
`ServiceContinuityVerified`	`Strict`-mode-only condition confirming the replacement pod is service-continuous. Under `Strict` mode, this — not `TrafficVerified` — is the condition that gates source-pod deletion (ADR-0352).
`RollingBack`	Controller is rolling back to the source pod state following a terminal error.
`Complete`	Migration completed successfully.

TrafficVerified and ServiceContinuityVerified are Condition types, not phases, and must never appear as a Phase: value. Which one gates source-pod deletion depends on tcpPreservationMode: TrafficVerified (ADR-0012) outside Strict mode, ServiceContinuityVerified (ADR-0352) under Strict mode.

MigrationPolicy

Group / Version / Kind: migration.podmotion.io/v1alpha1 / MigrationPolicy

Policy constraints governing which pods may be migrated and under what conditions. A MigrationPolicy can restrict migration to pods matching a label selector, enforce bandwidth caps, and define schedule windows during which migrations are permitted. The PodMigration controller evaluates applicable MigrationPolicy objects before advancing past Validating.

NodeMigrationCapacity

Group / Version / Kind: migration.podmotion.io/v1alpha1 / NodeMigrationCapacity

Per-node migration capability advertised to the migration scheduler. Each node agent writes a NodeMigrationCapacity object reflecting the installed CRIU version, whether containerd NRI is enabled, verified kernel feature flags, supported storage-migration tiers, network-continuity support, whether GPU migration (NVIDIA cuda-checkpoint) is available, and the maximum concurrent migrations this node can serve as source/destination. The scheduler reads these objects when selecting destination nodes and when enforcing concurrent migration limits across the cluster.

MigrationCheckpoint

Group / Version / Kind: migration.podmotion.io/v1alpha1 / MigrationCheckpoint

Represents a captured CRIU checkpoint artifact and its transfer state. A MigrationCheckpoint object is created by the controller during the Checkpointing phase and tracks the checkpoint image location, integrity hash, and transfer progress through Transferring. It is associated with its parent PodMigration via a label and a PodMigrationRef field, not a Kubernetes owner reference — cleanup is finalizer-driven, explicitly deleted by the controller rather than garbage-collected by an owner-reference cascade. Short name: mcp.

MigrationWebhookConfig

Group / Version / Kind: migration.podmotion.io/v1alpha1 / MigrationWebhookConfig

Admission webhook configuration for PodMotion. This CRD is scaffolding: the sole defined field is Foo *string. The webhook intercepts PodMigration CR creation; full webhook logic is planned for a future release. Storage migration is deferred to v1.2.

Version requirements

Requirement	Minimum	Tested
Kubernetes	1.27+	1.27 (kind, arm64)
Kernel	5.15+	6.8 only
Kernel config (PostCopy)	`CONFIG_USERFAULTFD=y`	verified on kernel 6.8

Kernel 5.15 is the functional floor for the bpfman TC egress attach point used by the PodMotion node agent (ADR-VersionRequirements). Kernel 6.8 is the only kernel on which proof runs have been executed — all earlier arm64/kind pgbench PoC and Sprint 30 results are on arm64 / Ubuntu 24.04 / kernel 6.8 / Flannel VXLAN. Behavior on earlier kernels is untested.

See Getting Started for full prerequisites.