Observability Reference

PodMotion v0.1.0-alpha

Metrics

PodMotion v0.1.0-alpha does not expose a Prometheus /metrics endpoint. Kubernetes status conditions on the PodMigration CR are the primary observability interface.

Prometheus metrics instrumentation is planned for a future release. No /metrics endpoint is registered in the operator or node agent binaries in v0.1.0-alpha.

Distributed Tracing

Distributed tracing (OpenTelemetry) is not instrumented in v0.1.0-alpha. Phase progress is observable via Kubernetes status conditions on the PodMigration resource (see below).

Status Conditions — Primary Observability Interface

The PodMigration CR exposes a .status.conditions array. Each condition follows the standard Kubernetes metav1.Condition structure with type, status (True / False / Unknown), reason, message, and lastTransitionTime. The CRD schema defines 14 condition types — this is the canonical count shared with the CRD reference page.

The 14 condition types are listed below. All condition names are pulled from the CRD schema (migration.podmotion.io_podmigrations.yaml) and the condition vocabulary in api/v1alpha1/podmigration_types.go. This is the canonical 14-count set; the CRD reference page lists the same 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. Source pod is eligible for deletion only after this condition is `True`.
`RollingBack`	Controller is rolling back to the source pod state following a terminal error.
`Complete`	Migration completed successfully.

Design guarantee (ADR-0012; verification modes defined in ADR-0055): The source pod is never deleted before TrafficVerified=True. This is enforced in the controller — source pod deletion is gated on TrafficVerified=True being observed. TrafficVerified is a Condition type, not a phase; it must never appear as a Phase: value.

Reading Conditions with kubectl

kubectl get podmigration <name> -o jsonpath='{.status.conditions}' | jq .

Or use kubectl describe for human-readable output:

kubectl describe podmigration <name>

Freeze Window SLO

p99 freeze window ≤ 487ms was measured on a single-container / single-TCP-flow migration, arm64 / Ubuntu 24.04 / kernel 6.8 / Flannel VXLAN (earlier arm64/kind pgbench PoC, 10 runs). The p50 was 312ms; minimum 259ms. Zero failed transactions and RST=0 were observed across all 10 runs.

Multi-container and multi-flow p99 values are not yet measured. These measurements do not carry over to other substrates, container counts, or flow counts until separate proof runs are recorded.

Checkpoint Observability

Checkpoints are stored on the node-local filesystem at /run/podmotion/checkpoints/<migration-ref>/ (tmpfs, mode 0700). They are written by the CRIU checkpoint step and consumed by the restore step on the destination node.

No checkpoint retention policy is automated in v0.1.0-alpha. Users must manage checkpoint cleanup manually. Orphaned checkpoint directories can accumulate on the source node if a migration is aborted after the checkpoint phase and before the restore phase completes cleanup.

Kubernetes events for checkpoint writes: PhaseTransition Kubernetes Events are emitted on the PodMigration object by the controller as the migration advances through phases. Structured audit logging (internal/audit/) is not implemented in v0.1.0-alpha — the audit/ directory is a stub. PhaseTransition events are emitted; structured audit records are not. A dedicated CheckpointWritten event (fired at the moment the CRIU dump completes) is also not yet implemented in v0.1.0-alpha. The CheckpointComplete status condition (see table above) is the authoritative signal that a checkpoint has been written successfully.

To observe checkpoint events:

kubectl get events --field-selector involvedObject.name=<podmigration-name>

There is no structured audit log to query in v0.1.0-alpha: the internal/audit/ package is a stub and emits no structured JSON records. Plain operator pod logs (kubectl logs -n podmotion-system deploy/podmotion-operator) carry unstructured phase-progress output only.