User guide: MigrationPolicy
Scopes migration bandwidth and concurrency to Machines matching a label
selector, instead of the global, cluster-wide
migration.maxConcurrentPerNode/migration.maxConcurrentCluster Helm
values -- Kairon's namespace-scoped equivalent of KubeVirt's own
MigrationPolicy CRD.
Example
apiVersion: kairon.zyvor.dev/v1
kind: MigrationPolicy
metadata:
name: web-tier
namespace: prod
spec:
selector: {tier: web}
bandwidthMbps: 500
maxConcurrent: 2
This applies to every Machine in the prod namespace labeled
tier: web, regardless of who creates the MachineMigration for it
(kaironctl evacuate, the dashboard, a direct kubectl apply, or
controller.cordonEvacuation) -- the same "applies automatically to
anything matching, not just one caller's own code path" shape
MachineDisruptionBudget already has. kaironctl get migrationpolicies
(or kubectl get migrationpolicies) lists what's configured, including
each policy's current status.activeMigrations count -- as does
kairon-ui's own read-only "Migration policies" dashboard page
(GET /api/v1/migration-policies).
Or, via kaironctl:
$ kaironctl create migrationpolicy web-tier --selector tier=web --bandwidth-mbps 500 --max-concurrent 2
migrationpolicy/web-tier created
$ kaironctl edit migrationpolicy web-tier --max-concurrent 4
migrationpolicy/web-tier updated
--selector is repeatable for a multi-label selector (--selector tier=web --selector env=prod). edit only patches the flags you actually pass --
omitting --bandwidth-mbps on an edit call never clears an
already-configured value back to 0.
How it's enforced
Both fields are enforced by kairon-controller's existing migration
reconcile loop, at the exact moment a Pending MachineMigration is
about to be admitted (the same point MachineDisruptionBudget/the global
concurrency caps are already checked):
maxConcurrentcaps how many non-terminal migrations of matching Machines may run at once, cluster-wide. A migration that would exceed it is leftBlockedwith a clear message (MigrationPolicy prod/web-tier: maxConcurrent reached) and retried automatically on a later tick, exactly like the globalmaxConcurrentPerNode/maxConcurrentClustercaps already behave. This is independent of, and in addition to those global caps -- both are checked, and either one blocking is enough to block the migration.bandwidthMbpsbecomes theMachineMigration's ownspec.bandwidthMbpsthe moment it's admitted, but only if thatMachineMigrationdidn't already set one explicitly -- an explicit per-migration--bandwidth-mbps(viakaironctl migrate) or a hand-writtenspec.bandwidthMbpsalways wins over any policy default. When more than oneMigrationPolicyin the namespace matches the same Machine, the first one found supplies the default -- deliberately not merged or most-restrictive, keeping this a simple default value, not a second competing enforcement layer on top ofmaxConcurrent.status.activeMigrationsis patched every tick, mirroringMachineDisruptionBudget's own purely-observational status reconciliation.
Adaptive live migration (experimental)
Adaptive migration is experimental until the 3-node lab migration matrix runs green; see docs/STATUS.md.
With strategy: adaptive, kairon-node watches each live transfer's telemetry and steers it when it stalls, instead of leaving the start-time settings in place until the transfer finishes or the operator cancels it:
apiVersion: kairon.zyvor.dev/v1
kind: MigrationPolicy
metadata:
name: databases
namespace: prod
spec:
selector: {tier: db}
strategy: adaptive # static (default) | adaptive
maxDowntimeMs: 250
completionTimeoutPerGiB: 120s
progressTimeout: 30s
autoConverge: {enabled: true, dirtyRateThresholdMbps: 750}
postCopy: {enabled: true, triggerAfter: 90s}
compression: {algorithm: zstd, level: 3}
bandwidth: {maxMbps: 10000, adaptive: true}
At admission, kairon-controller copies these settings into the migration's spec.adaptive, spec.maxDowntimeMs and spec.bandwidthMbps. Values set on the MachineMigration itself win, field by field, and later policy edits never change a migration already in flight. bandwidthMbps stays as a deprecated alias for bandwidth.maxMbps. Compression needs multifd, so admission sets multifdChannels: 2 when compression is on and the migration didn't choose a channel count.
The engine moves through these stages, skipping any remedy that is disabled or that the node can't do:
- PreCopy. The transfer runs with half of
maxDowntimeMsas its downtime limit. - AutoConverge. Guest vCPUs are throttled, with the ceiling raised from 50% to 75% to 99% while the transfer stays stalled.
- RelaxDowntime. The downtime limit rises towards
maxDowntimeMs, straight to QEMU's expected downtime when that fits. - PostCopy. The guest switches to running on the target while remaining pages are fetched over the network.
A transfer counts as stalled when remaining RAM hasn't shrunk by 5% within progressTimeout. In PreCopy it also counts as stalled when the guest dirties memory at or above the transfer rate, or reaches autoConverge.dirtyRateThresholdMbps. postCopy.triggerAfter switches to post-copy once the transfer has run that long, even with other remedies left. With bandwidth.adaptive, the transfer starts at a quarter of maxMbps and the bandwidth rises while throughput keeps up with it. If throughput falls well short, the bandwidth backs off. A transfer still running after guest RAM in GiB times completionTimeoutPerGiB, before post-copy, is aborted and the source keeps running.
Post-copy changes the failure model. Once post-copy starts, the guest's newest memory lives on the target and the rest on the source. If the transfer then fails, the migration goes to NeedsRecovery: Kairon neither resumes the source nor aborts the target, and spec.cancel is refused. Kairon never arms post-copy for a Machine with host devices (spec.deviceClaims or VFIO), when the source adapter can't switch a running transfer, or for multifd transfers on QEMU older than 10.0.
Adaptive control needs the migration adapter's optional tune, postcopy and capabilities routes (see docs/migration-adapter.md) on both nodes. With an older adapter the migration runs with its start-time settings and status.adaptive.stage reads Unsupported. The engine's state, including a capped log of every action it took, is in status.adaptive; transfer telemetry is in status.progress. kaironctl describe migration NAME prints both as a readable block, and Prometheus gets kairon_migration_progress, kairon_migration_adaptive_stage and kairon_migration_adaptive_actions_total (see observability).
Per-migration overrides on the command line:
$ kaironctl create migrationpolicy databases --selector tier=db --strategy adaptive --max-downtime-ms 250 --auto-converge --post-copy --post-copy-after 90s --compression zstd --compression-level 3
$ kaironctl migrate db-1 --strategy adaptive --progress-timeout 20s --post-copy=false
Previewing what a migration would get right now (kaironctl describe)
describe for every other kind in this project uniformly prints the raw
object as JSON and nothing else. kaironctl describe migrationpolicy is one
of only five deliberate exceptions (the others are kaironctl describe machine,
kaironctl describe snapshotschedule,
kaironctl describe quota,
and kaironctl describe budget):
it prints that same JSON, then appends exactly which Machines in the
policy's own namespace currently satisfy spec.selector, and for each one,
what creating a MachineMigration for it right now would actually get
from this policy:
$ kaironctl describe migrationpolicy web-tier
{
"apiVersion": "kairon.zyvor.dev/v1",
"kind": "MigrationPolicy",
...
}
Matching machines (2) -- status.activeMigrations 1/2; a migration created for each of these right now, in this order, would get:
web-1 admitted 500 Mbps (this policy)
web-2 BLOCKED (MigrationPolicy prod/web-tier: maxConcurrent reached) 500 Mbps (this policy)
Both columns come from calling kairon-controller's own exported, pure
controller.AdmitMigrationPolicy/controller.BandwidthMbpsFromPolicies --
the identical functions the migration reconcile loop itself calls for every
MachineMigration it admits -- so this preview can never disagree with what
the controller will actually do:
- Admission walks matching Machines in a stable, name-sorted order and
spends this policy's own
maxConcurrentcap as it goes, exactly like a real sequential batch of migrations created in that order would -- so once the cap is spent, every later match in the list correctly reportsBLOCKED, with the same blocker message the controller itself would record. - Bandwidth reports what
bandwidthMbpsa new migration for that Machine would actually inherit. When more than oneMigrationPolicyin the namespace matches the same Machine,spec.bandwidthMbpsfirst-match-wins semantics (see above) mean an earlier overlapping policy can win over the one you're describing -- the preview says so explicitly (from "other-policy", an earlier-matching MigrationPolicy, not this one) rather than silently reporting the wrong policy's number as this policy's own.
A selector matching zero Machines prints the same explicit (none -- check spec.selector against these Machines' own labels) hint
describe snapshotschedule uses. Like that preview, this is a snapshot of
this instant, not a guarantee -- a Machine's labels, this policy's own
spec.selector/maxConcurrent/bandwidthMbps, another overlapping
policy's fields, or status.activeMigrations itself can all change between
running describe and whenever a migration is actually created.
Falling back to a cold migration (spec.fallbackToCold)
A live migration that cannot start parks in Blocked by default: the
destination reports no live backend, the source adapter returns
unsupported, or the stream it negotiated cannot be used. Set
spec.fallbackToCold: true (kaironctl migrate --fallback-to-cold) to
continue as a cold migration instead. The agent aborts the prepared target,
resumes the source's network, stops the Machine and hands the migration to
the same cold path the controller uses (Stopping -> Restarting), with
status.effectiveStrategy: cold and a message naming the reason.
Cold stops the Machine, so it is down for the move; leave this off when
that is not acceptable. The fallback applies only before the source
transfer starts (the source is untouched at that point). It is never used
after a transfer began, and not when --migration-require-encrypted blocks
an unencrypted data plane, which stays Blocked.
Real limits today (first cut)
- Namespace-scoped only -- a
MigrationPolicyonly ever matches Machines in its own namespace, same asMachineDisruptionBudget. bandwidthMbpsis a default, not an enforced ceiling. Nothing stops an explicit per-migration--bandwidth-mbpsfrom setting a higher value than a matching policy's default -- this only fills in an unset value, it doesn't cap an explicit one.- No admission webhook. Like
MachineQuota's own reconcile-loop enforcement, aMachineMigrationcreated directly through the API is still fully subject to this (unlike a webhook, this can't be bypassed by skipping a CLI), but there's no immediatekubectl apply-time rejection either -- an over-cap migration is admitted asPendingand becomesBlockedon the very next reconcile tick, not instantly. - First-match-wins bandwidth defaulting, not merged. See above -- if
you need one Machine to definitely get a specific bandwidth regardless
of policy overlap, set
spec.bandwidthMbpson theMachineMigrationdirectly instead of relying on policy defaulting. - The
describepreview iskaironctl/kubectl-only, no dashboard equivalent yet.kairon-ui's "Migration policies" page still shows only the raw object andstatus.activeMigrations, not the per-Machine admission/bandwidth preview above.