What a Kubernetes migration involves
A Kubernetes migration moves running workloads from their current home onto a cluster you already operate or are building. The usual starting points are virtual machines, single Docker or Compose hosts, a cluster on one distribution that needs to move to another, and workloads that shift between clouds or data centers. Each starting point changes the work. A VM-based application usually needs containerization, configuration externalized from images, and a decision about whether it runs as a Deployment, StatefulSet or not at all. A Compose stack often maps to several Kubernetes objects, with volumes, networks and health checks needing explicit definitions.
The trigger shapes the timeline and the risk. Common triggers are the end of a hypervisor contract, a scheduled platform refresh, or a consolidation program that retires several smaller environments. A hypervisor deadline leaves little room for slow cutovers, so confirm early which workloads must move before the contract ends. A consolidation program often adds data center or cloud account moves on top of the container work, which multiplies the number of dependencies to map.
On the in-house versus partner question, small stateless workloads run by an experienced platform team often stay in-house, because the cutover risk is low and rollback is a redeploy. Stateful workloads, regulated data and a fixed cutover window usually lead buyers to a partner, since data moves, audit evidence and rollback rehearsal are where schedules slip. This page assumes a target cluster exists or is being built. Building that cluster is a separate project, covered on the Kubernetes implementation page, and its distribution, networking and storage choices should be settled before migration planning starts.
What the work includes
Each workstream below produces a named output that stays with your team after the migration, from the first inventory to the decommissioning list for source systems.
Workload inventory and dependencies
List every virtual machine, Docker host and service in scope, with its owner, runtime, ports, data stores, certificates, scheduled jobs and external endpoints. Map which services call which, and flag dependencies on shared mounts, host agents or licensed software that a cluster will not provide by default. Output: an inventory and dependency map that the wave plan is built from.
Containerization readiness assessment
Check each workload for a reproducible image build, configuration that can move out of the image into environment variables or mounted files, writes to local disk, logging to stdout or files, and health endpoints that show whether the process can serve traffic. Output: a readiness assessment per workload listing the changes required before it is built.
Manifests and Helm packaging
Convert the working runtime settings into Kubernetes manifests or Helm charts, including resource requests and limits, liveness and readiness probes, security context and the namespace layout. Decide which workloads stay as plain manifests and which need a chart with values per environment. Output: packaged workloads in version control with a reviewed promotion path.
Stateful data moves
Databases, file stores and queues need a copy, sync and cutover method that fits their write pattern, such as replication, dump and restore, or snapshot with a short write freeze. Check storage class behavior, volume sizing, backup before the move and whether the data can be copied back if the cutover fails. Output: a data move plan per store with restore steps tested beforehand.
Migration waves and cutover runbooks
Group workloads into waves by dependency and risk, so dependent services move together and lower-risk services prove the pipeline first. Each wave gets a step-by-step cutover runbook covering DNS or gateway changes, freeze windows, verification checkpoints and named decision owners. Output: a wave plan and one cutover runbook per wave.
Rollback criteria and post-cutover validation
Define in advance the measurable conditions that trigger a rollback, such as failed health checks, data mismatches or error rates above an agreed threshold, and rehearse the reverse path in staging. After cutover, validate functions, data, logs and alerts before any source system is retired. Output: rollback test records, validation results and a decommissioning list for source systems.
What drives cost and duration
This table lists the factors that most change the effort of a Kubernetes migration, why each one matters, and one practical way to keep it manageable.
| Driver | Why it moves effort | How to keep it down |
|---|---|---|
| Number and type of workloads | Each workload needs its own container image, manifests or Helm chart, resource requests, probes and a test plan. Stateless web services are far quicker to move than batch jobs, legacy daemons or workloads that expect a fixed host. | Group workloads into families with a shared pattern and migrate one family first to build a repeatable template. |
| Degree of statefulness | Data moves need storage class decisions, volume snapshots or replication, ordering rules between dependent services and a tested restore. Stateful services usually take the largest share of testing and cutover planning. | Keep data stores on their existing managed or highly available service where practical, and move only the stateless tier first. |
| Number of integrations and external dependencies | Every DNS record, certificate, identity provider, message queue, database endpoint and firewall rule the workload uses must be re-pointed or re-approved from the cluster network, which adds coordination with other teams. | Build an inventory of dependencies per workload before scoping and confirm which ones need a network change request. |
| Source platform (VMs, Docker hosts or another distribution) | Virtual machines usually carry undocumented packages, cron jobs and local file paths that must be turned into container config. Docker hosts are often closer to containers but still rely on host networking, bind mounts and compose files. Moving between distributions mainly changes ingress, storage and add-on details. | Capture the running configuration of each source system, such as package lists, compose files and mounts, and convert it into version-controlled manifests before the build starts. |
| Environments and cutover windows | Each environment (development, test, staging, production) needs its own configuration, secrets and validation. Cutover windows limit when data can be frozen or traffic switched, and a missed window can add a full repeat of rehearsal work. | Standardize one deployment pipeline across environments and agree cutover windows and rollback triggers with the business owners early. |
| Compliance scope | Systems under audit or regulatory control need evidence of access control, encryption, logging and change approval for the new platform as well as the old one. Dual running of old and new evidence often adds documentation and sign-off work. | Confirm with your auditor or assessor which controls apply to the new cluster and map them to the hardening work before migration starts. |
| Air-gapped or multi-cluster target | Air-gapped clusters need every image, chart and package mirrored into a private registry and upgraded offline. Multi-cluster designs add placement, failover, shared identity and per-cluster configuration to each workload. | Decide the cluster count and connectivity model before the first workload is containerized, and mirror artifacts through the same pipeline used for deployments. |
| Target cluster edition and tooling | The cost of the target distribution, support subscription, platform tooling and the people to run them is priced separately in the sibling implementation plan and cost of ownership pages. | Use those pages to compare edition and tooling options against the migration scope described here. |
Project phases and outputs
The sequence moves from an inventory of what runs today to a verified target platform, then to migrated workloads that have been cut over in controlled waves and retired from the old environment.
Discover and inventory current workloads
Your team and ours list every application, virtual machine or Docker host in scope, along with its dependencies, data stores, network paths, owners and recovery requirements. The output is a workload inventory with a proposed migration pattern for each item and a list of questions that need owner answers before design starts.
Design the target and check cluster readiness
The target cluster is designed around the inventory, covering the control plane layout, etcd backups, Pod Security Standards per namespace and the image registry that nodes will pull from. Readiness is confirmed against a written checklist before any workload moves. The output is an approved target design and a signed readiness checklist that includes a tested etcd snapshot and a working private registry.
Containerize and package workloads
Each in-scope application is converted into container images and Kubernetes manifests or Helm charts, with configuration moved out of images, secrets routed through the chosen secrets mechanism and resource requests set. The output is versioned images in your registry and packaged deployments that build from source control and deploy to a staging namespace.
Run a pilot migration of one low-risk workload
A stateless, low-impact workload is deployed, tested and moved to the cluster to prove the pipeline, the network path, logging and rollback steps. Results are reviewed with the owner. The output is a pilot record covering the test results, the observed issues, the fixes made to the templates and the rollback procedure confirmed in practice.
Move stateful data and prove restores
Databases and persistent volumes are moved using the replication or copy method chosen for each store, and every data set is restored from backup into a test environment before cutover. The output is a restore test report per data store showing the restore time observed and the data checks passed, which becomes the basis for the cutover plan.
Cut over in waves with rehearsals
Workloads move in agreed groups, each preceded by a full rehearsal against a copy of production data and an etcd snapshot taken before the change window. Rehearsals and pre-change snapshots are standard controls, so each window has a tested rollback path. The output is a completed cutover record per wave, with validation sign-off from the owners and the rollback decision recorded.
Decommission the legacy environment
After the agreed stabilization period, old virtual machines and Docker hosts are shut down, their backups are retained according to policy and access is removed. The output is a decommissioning record listing each retired system, the retained backups with their retention end dates and the final inventory showing what remains on the legacy platform.
What teams keep in-house and what they outsource
This table compares which Kubernetes migration tasks your team keeps and which a partner usually handles, with the skills each task needs and who signs off.
| Migration activity | Kept in-house (skills and owner) | Outsourced to partner (skills and owner) |
|---|---|---|
| Workload inventory | Application owners confirm each service, its dependencies and data. Skills: application knowledge. Owner: application owners. | Partner maps network paths, storage use and external calls from the inventory. Skills: Kubernetes networking. Owner: partner engineers. |
| Containerization | Platform team approves base images and runtime settings. Skills: release management. Owner: platform team. | Partner builds images, adds health probes and tests them against the application. Skills: application knowledge. Owner: partner, reviewed by app owners. |
| Manifest authoring | Platform team sets standards and reviews every manifest before merge. Skills: Kubernetes networking and storage. Owner: platform team. | Partner writes Deployments, Services, volumes and policies in Git. Skills: Kubernetes networking and storage. Owner: partner engineers. |
| Stateful data migration | Internal DBAs approve replication, cutover windows and restore tests. Skills: database administration. Owner: internal DBAs. | Partner designs the copy or replication path and runs rehearsals. Skills: database administration, Kubernetes storage. Owner: partner, approved by DBAs. |
| Cutover and rollback runbooks | Release manager approves go and no-go steps. Skills: release management. Owner: release manager with application owners. | Partner drafts step-by-step runbooks, timing checks and rollback triggers. Skills: release management, Kubernetes networking. Owner: partner. |
| Security review of workloads | Security engineers accept findings and record risk decisions. Skills: security engineering. Owner: internal security team. | Partner checks pod security, RBAC, Secrets handling and image sources. Skills: security engineering. Owner: partner, findings tracked internally. |
| Post-cutover behavior checks | Application owners confirm functional behavior after cutover and sign off. Skills: application knowledge. Owner: application owners. | Partner supplies logs, metrics and dashboards for owners to check. Skills: Kubernetes networking, observability. Owner: partner support. |
| Knowledge transfer | Platform team runs the cluster after handover and owns the runbooks. Skills: Kubernetes networking and storage. Owner: platform team. | Partner delivers walkthroughs, documentation and supervised runs. Skills: all listed skills. Owner: partner lead. |
What usually goes wrong
Most failed Kubernetes migrations trace back to a few predictable gaps between the old platform and the new one. Each card names one risk and the phase where it is cheapest to prevent.
Hidden local state and fixed addresses
Applications that write to local disk, assume a single host, or hard-code IP addresses break once pods are rescheduled. During discovery, inventory every file path, socket, and address the workload uses, and move session and cache data to shared services before containerizing.
Root containers blocked at admission
Images that run as root or request privileged capabilities are rejected once Pod Security Admission enforces the Baseline or Restricted standard on a namespace. In the containerization phase, build images that run as a non-root user, then test each workload against the target namespace label in staging before cutover.
Secrets copied into plain manifests
Teams often convert environment files or configuration into Kubernetes manifests that store credentials in readable YAML committed to Git or applied as plain Secrets. Set the secret source of truth during planning, enable encryption at rest on the cluster, and restrict list and watch access before any production secret is loaded.
Inconsistent persistent volume copies
Copying a database or file volume while the application still writes produces a backup that restores cleanly but contains partial transactions. For each stateful workload, define a write freeze or replication cutover in the cutover runbook, and verify the restored copy with the application's own integrity checks.
Missing or wrong health probes
Without readiness probes, traffic reaches pods before they can serve, and without liveness probes, hung processes stay in rotation. Define probes during containerization, set startup allowances for slow-starting services, and confirm in staging that a deliberately stalled dependency removes the pod from service.
Rollback that was never rehearsed
A cutover plan with no tested reverse path leaves the team choosing between a broken production service and an improvised fix. Rehearse the rollback in staging with the same data movement and DNS or gateway switch used at cutover, and record the measured time to restore the old path.
Tooling version skew
Helm charts, operators, CI runners, and kubectl clients built for one Kubernetes minor version can fail or silently misbehave on another. Check the target version's skew policy against every client and controller in the pipeline, and pin tool versions before the migration window opens. Depth on upgrade rules is covered in the Kubernetes upgrades and support page.
How the work changes by starting point
Most VM estates were never designed for containers, so the first job is deciding which workloads move as containers, which stay as VMs, and which need re-architecting. The work changes at every stage of the migration.
- Inventory: Map each VM to its owner, dependencies, open ports, cron jobs, local state and license terms. Many VMs hold configuration that nobody has documented.
- Packaging: Build container images from the application, not from a copy of the VM disk. Plan how configuration moves into ConfigMaps and Secrets.
- Data movement: Identify data on local disks and decide how it reaches persistent volumes. Confirm the storage class supports the access mode each workload needs.
- Cutover: Run old and new in parallel where the application allows it, then shift traffic and keep the VM available for rollback until the new service is verified.
- Related build detail: Storage and cluster sizing are covered in the Kubernetes implementation plan and cost topic, and backup of persistent volumes in the Kubernetes etcd backup and disaster recovery topic.
Docker and Compose hosts already run containers, so packaging is often the smallest change. The risk sits in the host-level behavior that Compose hides from the application.
- Inventory: List every Compose file, its networks, volumes, environment files, restart policies and host bind mounts. Note which services depend on a specific host IP or port.
- Packaging: Convert Compose services into Deployments, Services and Ingress objects. Replace bind mounts with volumes, and check images for root-only assumptions that Pod Security Standards may block.
- Data movement: Named volumes on a host must be copied into persistent volumes. Confirm ownership and file permissions survive the copy.
- Cutover: Move one stack at a time. Keep the Compose host running and reverse the DNS or load balancer change if the new service fails.
- Related build detail: Access and pod restrictions are covered in the Kubernetes security hardening topic, and secrets moved out of environment files in the Kubernetes secrets management and encryption at rest topic.
Moving between distributions keeps the workloads in the same API model, so the manifests often carry over. The differences sit in the platform layer: ingress, storage, networking, identity and the way the control plane is run.
- Inventory: Record every cluster add-on, custom resource, operator, admission policy and ingress class. Check which API versions the source cluster serves and which the target supports.
- Packaging: Keep manifests in Git and parameterize distribution-specific settings. Confirm the target provides the storage classes and load balancer integration the workloads expect.
- Data movement: Back up persistent volumes with a tool that works on both sides, and test restores on the target before any cutover date is set.
- Cutover: Use a second cluster and shift traffic gradually. Plan how the source cluster is kept for rollback and when it is decommissioned.
- Related build detail: Conformance and support differences are covered in the Kubernetes distribution selection topic, and the version rules for the target in the Kubernetes upgrades and support topic.
Moving between clouds, or from a managed service to a self-managed cluster, means you take on work the provider used to do. The application is usually portable, but the cluster operations are not.
- Inventory: List provider-specific features in use, such as managed identity, load balancer annotations, storage classes, node pools and managed databases. Each one needs a replacement or a documented gap.
- Packaging: Remove cloud-specific annotations from manifests where possible. Plan how the control plane, etcd, certificates and node upgrades will be handled after the move.
- Data movement: Move object storage, managed database snapshots and volume data across network and egress paths you have costed. Confirm the transfer window fits your change process.
- Cutover: Keep DNS and certificate changes in a runbook with rollback steps. Test failover of the new control plane before traffic moves.
- Related build detail: Control plane design is covered in the Kubernetes high availability topic, and cost of self-management in the Kubernetes cost of ownership and editions topic.
An air-gapped target changes the supply chain for every component. Images, charts, packages and certificates must reach the cluster through a controlled transfer process before the migration can start.
- Inventory: Build a complete list of container images, Helm charts, operators and OS packages, including the transitive dependencies of each add-on. Missing one image can block the cutover.
- Packaging: Mirror images and charts into a private registry and repository. Kubeadm can pull control plane images from a private registry using the image repository setting, so confirm the mirror path before the build.
- Data movement: Plan how backups, container layers and data sets cross the boundary. Record the transfer approval steps, since each one adds time.
- Cutover: Rehearse the cutover inside the isolated network. Confirm that rollback images and the previous release remain available offline.
- Related build detail: Mirroring, certificate handling and offline upgrades are covered in the Kubernetes air-gapped installation topic.
What you need to provide
A Kubernetes migration moves faster and fails less often when the client supplies the decisions and access that only the client can give. The list below is what we need before planning is finished. Missing items do not stop the work, but they push the cutover date back, usually at the point where a workload is half moved. Start with a named owner for each application. The owner decides whether a workload is containerized, what its health checks mean, and whether it can accept a cutover window. Without that person, questions about configuration drift or unexpected dependencies stay open, and the team has to guess at the answers.
Next, give us access to the source environments and their configuration: virtual machine inventories, Docker host compose files, load balancer rules, scheduled jobs and the secrets each service reads today. We also need current backup and restore evidence for every stateful system, meaning the last successful restore test and its result. Without restore evidence, we cannot set a rollback point for data moves, and a failed cutover may have no clean way back. Data classification and residency rules determine where persistent volumes, backups and container images may live, and which regions or clusters may hold them. Network and DNS change authority decides who can alter routes, certificates and records during cutover. Also agree on change windows and a staging environment that mirrors production in versions, network policy and storage class. Finally, decide the image registry and the secret store before the first image is built. Choosing them late forces rebuilds and re-keying of every workload.
Frequently asked questions
How much effort does a Kubernetes migration take, and what drives it?
Effort depends mainly on how many workloads move, how many other systems each one depends on, and how much containerization work is needed before anything can run on the cluster. Workloads that already run as containers with externalized configuration usually take less work than virtual machines with hard-coded paths, local state or manual deployment steps. Stateful data moves, network and storage design, identity integration and cutover rehearsals add effort on top. DeployOpen does not quote effort figures in this FAQ. The written scope sets the deliverables, milestones and effort for a fixed-scope agreement, and it is agreed before work starts.
How long does a Kubernetes migration take to finish?
The inventory sets the duration. Until every workload, dependency, data store, integration and owner is listed, no reliable schedule exists, so the first phase is a discovery pass that records what runs where, what it connects to and how it is deployed. Once that list exists, the number of migration waves, the number of stateful systems and the number of cutover windows determine the timeline. Ask for the schedule in the written scope, which should show phases, milestones and the dependencies on your side. Any duration given before the inventory is complete is an assumption to test.
Can our own team migrate to Kubernetes without an outside partner?
Yes, a capable internal team can migrate its own workloads, especially if it already runs containers and operates Linux, networking and storage well. The gaps usually appear in cluster operations: upgrade planning, certificate handling, etcd backup and restore, identity integration and rehearsing cutover under time pressure. Ask whether the team has completed a production cutover before and who will own the platform after the move. A partner can take on defined parts of the work under a fixed-scope agreement, such as the inventory, migration waves or rollback rehearsals, while your staff keep ownership.
What does a Kubernetes migration need from our internal staff?
Expect your staff to provide system owners, access to the source environments and the target cluster, change windows, decisions on identity and networking, and people who can test each migrated service. Named owners for each application matter most, because they confirm expected behavior, sign off cutover and approve rollback. Security and compliance staff should review secrets handling, network exposure and audit logging early rather than at the end. Ask for the inputs to be listed by role and by phase in the proposal, so you can confirm capacity before work starts.
How are stateful databases moved during a Kubernetes migration?
Stateful databases are moved with a method chosen for each engine and its size, such as replication into the new environment followed by a planned switchover, or a dump and restore during a maintenance window. The choice depends on acceptable downtime, data volume, write rate, and whether the database already has tested backups and point-in-time recovery. Persistent volumes need storage class and snapshot planning, and etcd is backed up separately from application data. Before cutover, verify row counts, checksums and application reads and writes against the new instance. Confirm the approach for each database in the written scope.
Does rollback still work after cutover to Kubernetes?
Rollback works only if the plan keeps the old environment intact and defines how data flows back. For a stateless service, that usually means keeping the previous deployment ready and shifting traffic back through DNS, a load balancer or the ingress layer. For databases, reverse replication or a defined reconciliation step is needed, because writes made on the new platform do not appear in the old one by themselves. Decide the rollback trigger, the time limit and the owner before each wave, and rehearse it in staging. Retire the old environment only after the agreed stability period has passed.
How DeployOpen delivers migrations
DeployOpen plans, builds and hands over Kubernetes migrations inside infrastructure you control, under a written scope agreed before work starts. Each stage produces documented deliverables your team can review, test and run after the engagement ends.
How we scope
- Inventory each workload to be moved, with its runtime, dependencies, data stores and current hosting, whether virtual machines, Docker hosts or another cluster.
- Assess containerization readiness per workload, including configuration, state handling, secrets and logging, and record which items need code or build changes.
- Agree the target cluster design, cutover order, rollback criteria and acceptance tests in a written scope before any build work begins.
How we build
- Prepare container images, Helm charts or manifests, and deploy them to a staging cluster that matches the production design.
- Plan stateful data moves with tested copy, sync and validation steps, and rehearse them so the production window is predictable.
- Run cutover rehearsals with documented rollback steps, including DNS, load balancer and traffic switch sequences for each workload.
How we hand over
- Deliver runbooks for each migrated workload covering deployment, scaling, cutover, rollback and known operational limits.
- Document the final architecture, configuration, access model and the evidence from acceptance and rollback tests for your records.
- Walk your platform and application teams through the handover and confirm who owns each workload, alert and backup after go-live.
How we support
- Agree in the written scope which post-cutover items are included, such as hypercare, defect fixes and decommissioning of old hosts.
- Offer ongoing support, upgrades and continuous testing as a retainer if you want DeployOpen to keep operating the platform after handover.
- Confirm with your team the terms for support windows, response expectations and change control before the engagement starts.
