DRAFT PROPOSAL — NOT YET IMPLEMENTED: The kubectl podmotion plugin does not ship in v0.1.0-alpha. All commands on this page are unimplemented. The current interface is the PodMigration CRD — see the CRD Reference for the real workflow.

CLI Reference

Current Interface (v0.1.0-alpha)

In v0.1.0-alpha, the only supported interface is the PodMigration CRD. There is no kubectl plugin. Apply a PodMigration manifest directly:

kubectl apply -f podmigration.yaml

To inspect migration resources:

# List all PodMigration resources (full name)
kubectl get podmigration

# List using the short name
kubectl get pm

# Describe a specific migration
kubectl describe podmigration my-migration

Minimal PodMigration CR example:

apiVersion: migration.podmotion.io/v1alpha1
kind: PodMigration
metadata:
  name: my-migration
  namespace: default
spec:
  podName: my-pod
  podNamespace: default
  targetNodeName: worker-node-2   # optional: pin destination node
  mode: PreCopy                   # optional: PreCopy (default) | PostCopy | Cold
  tcpPreservationMode: None       # optional: None (default) | Strict | BestEffort
  dryRun: false                   # optional: validate without executing (default false)

Field notes:

• podName — name of the pod to migrate (required)
• podNamespace — namespace of the source pod (required)
• targetNodeName — optional destination node pin (user-authored); destinationNode is a separate controller-written field — do not author it in manifests
• mode — migration strategy: PreCopy (default, iterative memory pre-copy) | PostCopy (on-demand page pull after cutover) | Cold (stop-and-copy); field name is mode, not --strategy
• tcpPreservationMode — None (default, no TCP preservation) | Strict (hard guarantee, migration aborts if TCP state cannot be preserved) | BestEffort (attempt preservation, proceed on failure); opt-in to Strict or BestEffort — never on by default
• dryRun — validate the migration request without executing; default false
• The source pod is never deleted before TrafficVerified=True (guaranteed by design; ADR-0012)

See the CRD Reference for the full field specification and status conditions.

Planned kubectl Plugin (Draft — not yet implemented)

The sections below describe a kubectl podmotion plugin planned for a future release. None of these commands are available in v0.1.0-alpha. The examples below are illustrative only and must not be copy-pasted as working commands.

Installation

Not available. There is no published krew plugin — kubectl krew install podmotion does not work and will not find any plugin. This is the proposed post-release install command, shown for reference only.

# Proposed only — no such krew plugin is published in v0.1.0-alpha.
kubectl krew install podmotion

migrate

Initiate a live pod migration.

kubectl podmotion migrate \
  --pod <podName> \
  --namespace <podNamespace> \
  --destination <node>

Flags:

Example (illustrative — unimplemented):

kubectl podmotion migrate \
  --pod my-pod \
  --namespace default \
  --destination worker-node-2 \
  --tcp-preservation None

status

Check the status of an active or completed migration.

kubectl podmotion status --migration <name> --namespace <namespace>

Example output (illustrative — unimplemented):

Migration: my-migration
  Pod:         my-pod (namespace: default)
  Phase:       Complete
  TCP Mode:    None
  Conditions:
    TrafficVerified: True

list

List all PodMigration resources in a namespace.

kubectl podmotion list --namespace <namespace>

cancel

Cancel an in-progress migration. The source pod is never deleted before TrafficVerified=True (ADR-0012); cancellation before that condition is met leaves the source pod intact.

kubectl podmotion cancel --migration <name> --namespace <namespace>

logs

Stream migration controller logs for a specific migration.

kubectl podmotion logs --migration <name> --namespace <namespace> --follow

Reminder: The kubectl plugin described above is a draft proposal. The current interface in v0.1.0-alpha is the PodMigration CRD only. See the CRD Reference for the authoritative field reference.