CRD / Interface Reference

WARNING

There is no kubectl podmotion plugin in this release. PodMotion's only shipped user interface is the PodMigration custom resource applied with kubectl apply. A kubectl migrate plugin is described in docs/kubectl-migrate-proposal.md (Status: Draft, 2026-06-09) and is proposed — not yet shipped. Everything in that proposal is unimplemented.

The shipped interface: `kubectl apply`

You drive a migration by applying a PodMigration CR. There is no plugin binary in cmd/ — that directory contains only operator binaries (manager, node agent, a build-tagged scheduler stub, and a chained CNI plugin).

# Create or update a migration
kubectl apply -f podmigration.yaml

# List migrations (shortName pm, category podmotion)
kubectl get pm
kubectl get podmotion

# Inspect status, phase, and conditions
kubectl get podmigration <name> -o yaml

# Cancel/clean up by deleting the resource
kubectl delete podmigration <name>

`PodMigration` spec fields

The fields below are read directly from the CRD type definition (api/v1alpha1/podmigration_types.go). They are not auto-generated from any cobra command tree — no such tree exists in this repository.

Field	Type	Default	Constraints
`podName`	string	—	Required
`podNamespace`	string	—	Required
`sourcePodUID`	string	—	optional
`targetNodeName`	string	—	optional; scheduler picks if empty
`migrationPolicyRef`	LocalObjectReference	—	optional
`mode`	enum	`PreCopy`	`PreCopy` \| `PostCopy` \| `Cold`
`preCopyMaxRounds`	int32	`5`	1–20
`preCopyDirtyThresholdMB`	int32	`64`	min 1
`bandwidthLimitMbps`	int32	`0`	min 0 (0 = unlimited)
`completionTimeoutSeconds`	int32	`600`	min 30
`storageStrategy`	enum	`Auto`	`Auto` \| `Skip` \| `Sync` \| `SnapshotClone` \| `DualEngine`
`tcpPreservationMode`	enum	`None`	`Strict` \| `BestEffort` \| `None`
`freezeWindowBudgetMs`	int32	`500`	50–10000
`applicationProbe`	ApplicationProbeSpec	—	optional; protocol `SQL`/`HTTP`/`gRPC`/`TCP`, `timeoutSeconds` default 5
`dryRun`	bool	`false`
`rollbackOnFailure`	bool	`true`
`destinationCluster`	string	—	reserved post-v1.0 (intra-cluster only)
`sourcePodIP`	string	—	Calico/Cilium only
`affinityMode`	enum	`strict`	`strict` \| `patch` \| `ignore` (`patch` is post-beta only)

destinationNode is controller-set and should not be specified by users.

WARNING

tcpPreservationMode defaults to None — TCP connection continuity is off by default and the TCPVerifying phase is skipped. Set Strict (hard rollback on continuity failure) or BestEffort (warning only) to opt in.

Status: phases and conditions

status.phase follows the MigrationPhase enum (22 values total — see api/v1alpha1/podmigration_types.go for the complete list). Partial list: Pending, Validating, Checkpointing, PreCopyMemory, SocketInventory, ZeroWindowArm, OverlayHandoff, Transferring, Restoring, RestoreSocketReattach, DisengageHold, TCPVerifying, ServiceVerifying, CutoverComplete, Complete, DryRunComplete, Failed, RollingBack.

status.conditions uses these exported condition types (podmigration_types.go):

SocketInventoryComplete        DestinationNetnsReady
ZeroWindowArmed                ZeroWindowDisarmed
VXLANFDBUpdated                TCPSequenceContinuityVerified
ConnectionCountParity          RelayProgramsLoaded
RelayArmed                     OverlayReady
TCPVerified                    ServiceVerified
SocketsLive                    ProcessResumedAfterSocketsLive

TCPVerified is the aggregate TCP gate. TCPSequenceContinuityVerified=True corresponds to seq_delta=0 (zero dropped TCP sequence numbers). SocketsLive / ProcessResumedAfterSocketsLive enforce the SIGCONT-after-sockets-live ordering invariant.

Proposed CLI (not shipped)

docs/kubectl-migrate-proposal.md (Draft) outlines a future three-phase roadmap: an operator-provided kubectl-podmotion plugin (in an external repo, not in this tree), a SIG-CLI KEP for a built-in kubectl migrate gated behind KUBECTL_MIGRATE=1, and an upstream migration.k8s.io API object. All proposed flags (--to-node, --dry-run, --wait, --strategy, …) are unimplemented, and the proposal's field names (sourcePodName/sourcePod) do not match the real CRD (podName/podNamespace). Use kubectl apply until a plugin ships.