Docker Compose to Managed Kubernetes Migration Checklist

Serdar Tekin
Serdar Tekin
Co-Founder & CTO
Updated Nov 17, 202617 min read
Written for: Developers and platform teams moving production Docker Compose workloads to managed Kubernetes.
KubernetesDocker ComposeMigrationManaged KubernetesKomposeDevOps
Last reviewed:
Guide
Docker Compose to Managed Kubernetes Migration Checklist
rafftechnologies.com/learn
On this page

Key Takeaways

Treat conversion as a starting point. Separate state, define probes and traffic paths, size workers from requests, and keep one authoritative write path plus a tested rollback during cutover.

Free control plane

Move from Compose to managed Kubernetes with a free control plane.

CNCF-certified Kubernetes with a free control plane. Add nodes when you need them, with no egress fees.

Docker Compose to Kubernetes migration is not a YAML conversion project. It is an application-architecture migration: state, health checks, configuration, traffic, secrets, scaling, and rollback all need new ownership before production traffic moves.

Kompose can translate a Compose file into Kubernetes objects, but Kubernetes documentation treats it as a conversion aid, not a production-readiness system. Generated manifests still need review for storage, probes, exposure, resource requests, update strategy, and security.

Raff Technologies managed Kubernetes removes the need to operate the control plane yourself, but it does not remove application migration work. The safest path is:

inventory → separate state → map services → add probes/resources → validate traffic → test recovery → cut over → observe → decommission Compose

If you are still deciding whether Kubernetes is justified, start with Kubernetes vs Docker Compose for Small Teams. This guide assumes the decision to migrate has already been made.

Start with a Compose workload inventory

Before converting anything, inventory the running application.

A Compose file may describe containers, ports, networks, volumes, environment variables, and health checks, but production behavior often depends on things outside the file.

Record:

  • images and commands;
  • internal and public ports;
  • named volumes and bind mounts;
  • environment variables and secrets;
  • health checks;
  • databases and caches;
  • scheduled tasks;
  • background workers;
  • DNS and TLS;
  • object storage;
  • external APIs;
  • backup jobs;
  • CI/CD credentials;
  • host cron jobs;
  • host filesystem dependencies.

A useful migration table is:

Compose concernWhat to captureKubernetes destination
serviceimage, command, replicasDeployment, StatefulSet, Job, or external service
published portpublic or internal purposeService + Gateway/Ingress/LoadBalancer decision
named volumeowner, size, backupPVC, object storage, managed service, or external storage
bind mountwhy host filesystem is neededimage content, ConfigMap, Secret, PVC, or redesign
environmentconfig vs secretConfigMap, Secret, or external secret workflow
healthcheckwhat healthy meansstartup, readiness, liveness probes
depends_onstartup expectationretries, readiness, service discovery
databasedata lifecycle and recoverymanaged DB, external DB, or deliberate StatefulSet design
cronschedule and concurrencyCronJob
one-off taskretries and completionJob

The first deliverable is not Kubernetes YAML.

It is a map of what moves, what remains external, and which Compose assumptions must disappear.

Do not move hidden host dependencies into Kubernetes unchanged

Compose deployments often work because one VM quietly provides extra services.

Examples include:

  • uploads under /srv/app;
  • TLS certificates mounted from the host;
  • cron scripts outside Compose;
  • local backup directories;
  • application sessions stored on disk;
  • host-level firewall rules;
  • a reverse proxy configured outside the Compose file.

Kubernetes will not discover these dependencies automatically.

For every host dependency, choose one destination:

  1. bake it into the container image;
  2. move it to ConfigMap or Secret;
  3. move it to persistent storage;
  4. move it to object storage or another managed service;
  5. remove the dependency entirely.

A successful migration ends with the old VM no longer being a hidden runtime dependency.

Separate state before making Pods replaceable

Kubernetes assumes Pods can be recreated.

That makes state the highest-risk part of most Compose migrations.

Classify every writable path:

Disposable runtime data

Examples:

  • temporary files;
  • caches that can be rebuilt;
  • transient build output.

These usually do not need persistent storage.

Configuration

Configuration belongs in controlled deployment configuration, ConfigMaps, Secrets, or application defaults rather than mutable container filesystems.

Durable filesystem data

Uploads or application data that genuinely require mounted filesystem semantics may need a PersistentVolumeClaim.

Use Kubernetes Persistent Storage before mapping Compose volumes directly to PVCs.

Database state

A database should move into Kubernetes only if the team intentionally wants to own:

  • persistent storage;
  • backup consistency;
  • restore;
  • upgrades;
  • failover;
  • resource guarantees;
  • maintenance.

For many small teams, keeping the database managed or external reduces migration risk.

The target architecture may become:

Text
Managed Kubernetes ├── web Pods ├── API Pods └── worker Pods ↓ managed database ↓ object storage / persistent storage

The objective is not "move every Compose container into Kubernetes."

It is "move the application into an operating model where compute can be replaced safely."

Map Compose services to the right Kubernetes workload type

Not every Compose service becomes a Deployment.

Use workload behavior:

WorkloadKubernetes starting point
stateless web/APIDeployment
long-running workerDeployment
stateful identity/order requirementStatefulSet
scheduled taskCronJob
one-time migration/taskJob
external managed DB/cacheno in-cluster workload required

A StatefulSet is not a generic choice for anything with data.

Use it when stable Pod identity, ordered lifecycle, or per-replica persistent storage is genuinely required.

Keep the target architecture simpler than the source where possible.

Convert Compose health checks into separate Kubernetes probes

Compose commonly has one health check.

Kubernetes separates health into three signals.

Startup probe — has the application completed startup?

Readiness probe — should this Pod receive traffic?

Liveness probe — is the process stuck badly enough that Kubernetes should restart it?

Do not copy one Compose health command into all three.

For every service, define:

ProbeQuestion
startupHow long can this service legitimately take to initialize?
readinessWhat must be true before production traffic reaches it?
livenessWhat proves the process cannot recover without restart?

Be careful with dependency checks.

A temporary database outage may justify failing readiness, but making liveness fail on every dependency issue can create restart loops that make recovery harder.

Also remove startup-order assumptions from Compose depends_on. Kubernetes workloads can restart independently at any time. Applications should retry dependencies and tolerate temporary unavailability.

Replace Compose networking with Kubernetes Services and deliberate traffic entry

Compose service names provide convenient discovery on a Docker network.

Kubernetes uses Services to provide stable identities to replaceable Pods.

For each connection, classify it as:

  • internal service-to-service traffic;
  • external dependency;
  • public application traffic;
  • administrative access.

Most application Services should remain internal.

A common target is:

Text
Internet ↓ Gateway API or existing Ingress ↓ ClusterIP Service ↓ application Pods ↓ private Services / managed dependencies

Do not turn every published Compose port into a public Kubernetes Service.

Re-evaluate why the port existed.

For new HTTP/HTTPS routing designs, evaluate Gateway API where your cluster implementation supports the required features. Existing Ingress remains valid, but Kubernetes has frozen the Ingress API and new routing functionality is developed through Gateway API.

Use Kubernetes Services Explained for Service types and Kubernetes Load Balancer vs Ingress Controller for the exposure decision.

Configuration and secrets need a new ownership model

Compose deployments frequently rely on environment variables and .env files.

During migration, separate:

Non-secret application configuration

Good candidates for ConfigMaps or deployment configuration include:

  • feature switches;
  • service URLs;
  • environment names;
  • application tuning values.

Secrets

Credentials, tokens, API keys, and private connection strings require controlled secret handling.

Do not copy a production .env file into Git-tracked Kubernetes manifests.

Kubernetes Secrets provide a cluster object for sensitive values, but teams still need:

  • RBAC;
  • rotation;
  • access ownership;
  • safe CI/CD injection;
  • protection of kubeconfig and administrative credentials.

The migration is a good time to remove long-lived secrets from application images and source repositories.

Set requests before sizing the worker pool

Compose can run several containers on one VM without explicit CPU or memory requests.

Kubernetes scheduling works differently.

For every production workload, define initial CPU and memory requests based on observed behavior or conservative estimates.

Then calculate the cluster.

Use Kubernetes Cluster Sizing to include:

  • Node Allocatable;
  • minimum replica demand;
  • system overhead;
  • rollout overlap;
  • one-worker failure or maintenance reserve;
  • growth headroom.

Do not choose worker plans first and then force workloads to fit.

Calculate workload requirements first.

Keep node-pool design simple during migration

A migration does not need a new node pool for every Compose service.

Start with one general pool unless a workload class clearly needs:

  • a different CPU/memory shape;
  • dedicated capacity;
  • a separate scaling pattern;
  • stronger compute placement;
  • different maintenance behavior.

Then use Kubernetes Node Pools.

Too many pools during migration create extra variables when the team is already changing networking, storage, scheduling, and deployment behavior.

Use Kompose as a starting point, not as the migration strategy

Kompose remains useful.

The Kubernetes documentation shows the basic workflow:

Text
kompose convert kubectl apply -f <generated-output>

It can convert common Compose concepts into Kubernetes resources.

But generated output must be reviewed.

Check at least:

  • workload type;
  • Service exposure;
  • volumes;
  • probes;
  • resource requests;
  • Secrets;
  • update strategy;
  • security context;
  • labels;
  • naming;
  • storage lifecycle.

Kompose can accelerate the first draft.

It cannot decide whether a database should remain external, whether a service should be public, what readiness means, or whether rollback is safe.

That is why this page should own migration architecture, not compete for the generic Kompose keyword.

Build the target environment before changing production traffic

The Kubernetes environment should be functional before cutover.

Validate:

Cluster

  • worker capacity is sufficient;
  • node pools are correct;
  • required storage exists;
  • cluster access works;
  • monitoring is available.

Workloads

  • images deploy reproducibly;
  • Pods reach Ready;
  • replicas schedule correctly;
  • Jobs/CronJobs behave correctly;
  • Secrets and ConfigMaps are present.

Networking

  • internal Services resolve;
  • public routes work;
  • TLS is valid;
  • required external APIs are reachable;
  • private dependencies are not accidentally public.

State

  • persistent data is present;
  • databases are reachable;
  • uploads behave correctly;
  • backup and restore are validated.

Operations

  • logs are visible;
  • failed Pods are diagnosable;
  • a new image can roll out;
  • rollback has been tested.

Do this before changing the production DNS or routing path.

Use an explicit production cutover gate

Production should not move because the new cluster "looks fine."

Use a written gate.

GateAcceptance condition
Imagesversioned and reproducible
Stateevery durable path has an owner
Databasebackup, restore, and schema compatibility are understood
Replicasmulti-replica workloads do not depend on local state
Probesstartup, readiness, and liveness behave correctly
ResourcesCPU and memory requests are set
Secretsno production secrets are embedded in images/manifests
Trafficpublic and internal paths are clearly separated
DNS/TLSproduction hostnames and certificates work
Jobsworkers, CronJobs, and migrations have explicit ownership
Observabilitylogs, metrics, events, and application errors are visible
Rolloutnew versions can deploy safely
Rollbackprevious app and traffic path remain recoverable
Datathere is one authoritative write path
Cutoverowner, window, checks, and abort criteria are written

Every item needs a pass/fail condition.

Avoid split-brain data during cutover

The hardest migration problem is often not containers.

It is data ownership.

If both Compose and Kubernetes accept writes against independent state, rollback becomes dangerous.

Prefer one authoritative write path.

Possible strategies include:

  • keep the database external and shared during the compute migration;
  • briefly stop writes while final data synchronization occurs;
  • switch application traffic atomically enough that only one environment accepts writes;
  • design replication explicitly if dual-running is required.

Do not improvise this during the migration window.

If the database schema also changes, verify that the previous application version can still operate against the new schema before treating application rollback as safe.

Keep the Compose environment recoverable after cutover

Kubernetes Deployments can roll back application revisions, but migration rollback is broader.

Keep the old Compose environment recoverable until the new deployment has passed an agreed observation period.

That can mean:

  • keep the VM powered on but outside the active traffic path;
  • preserve image versions and configuration;
  • prevent it from creating conflicting writes;
  • keep a documented DNS/routing reversal procedure;
  • define who can order rollback.

Do not destroy the old environment after the first successful HTTP request.

Decommission it only after the new environment has proven:

  • traffic;
  • state;
  • jobs;
  • monitoring;
  • deployment;
  • backup;
  • recovery.

How Raff Kubernetes changes the migration boundary

Raff Managed Kubernetes currently provides:

  • a $0 standard control plane;
  • optional three-master HA for $30/month;
  • worker nodes starting at $9.99/month;
  • Standard 2 vCPU / 4 GB workers at $17.99/month;
  • multiple node pools;
  • autoscaling;
  • private VPC networking;
  • a managed public endpoint with DNS and TLS;
  • built-in monitoring and pod logs;
  • dedicated Kubernetes storage at $0.10/GB-month.

Use the Raff Kubernetes product page for live pricing and platform capabilities.

For migration planning, this means the team can focus on application workloads and worker capacity without building and operating its own Kubernetes control plane.

It does not mean the platform can infer:

  • which Compose volume contains critical data;
  • whether a health endpoint is a readiness or liveness signal;
  • whether a port should be public;
  • whether a schema migration is reversible;
  • whether an application can run multiple replicas safely.

Those remain application migration decisions.

For a production Compose workload, use this order:

Phase 1 — Inventory

Document services, ports, state, secrets, jobs, external dependencies, and host assumptions.

Phase 2 — Separate state

Move or deliberately map databases, uploads, and persistent filesystem data.

Phase 3 — Build Kubernetes workload definitions

Choose Deployment, StatefulSet, Job, and CronJob objects intentionally.

Phase 4 — Add production controls

Define probes, resource requests, Services, routing, Secrets, and storage.

Phase 5 — Create the cluster

Size workers and node pools from the actual workload model.

Phase 6 — Validate without production traffic

Test application behavior, state, monitoring, rollout, and recovery.

Phase 7 — Cut over

Switch one authoritative traffic/write path with explicit validation and abort criteria.

Phase 8 — Observe

Keep Compose recoverable while Kubernetes proves normal operations.

Phase 9 — Decommission

Remove the old environment only when it is no longer a runtime or recovery dependency.

Final recommendation

Do not migrate Docker Compose to Kubernetes by starting with YAML conversion.

Start with the application.

Inventory its dependencies, separate persistent state, translate health into Kubernetes probes, replace host networking assumptions with Services and deliberate public routing, set resource requests, and define rollback before production traffic moves.

Use Kompose when it saves time generating a first draft, then review every generated resource as production code.

A successful migration is complete when the application can be scheduled, replaced, deployed, observed, and recovered without depending on the old Compose host.

Continue with Kubernetes Cluster Sizing, Kubernetes Node Pools, Kubernetes Persistent Storage, and Managed vs Self-Managed Kubernetes for the decisions behind the target platform.

Move to Raff Kubernetes when your state model, health checks, worker capacity, traffic path, and rollback plan are ready for production cutover.

Free control plane · 14-day money-back guarantee

Deploy a Cluster Now
Was this article helpful?
Serdar Tekin
Serdar Tekin
Co-Founder & CTO

Co-Founder & CTO at Raff, focused on cloud infrastructure, systems architecture, security, reliability, and production operations.

Free control plane

Move from Compose to managed Kubernetes with a free control plane.

CNCF-certified Kubernetes with a free control plane. Add nodes when you need them, with no egress fees.

14-day money-back guarantee

Frequently asked questions

Can Kompose fully migrate a production Docker Compose application?
No. Kompose can generate Kubernetes objects from Compose, but production migration still requires review of state, probes, networking, resources, secrets, rollout, and recovery.
Should a database move into Kubernetes during a Compose migration?
Not automatically. Keep it managed or external when that reduces risk, or run it in Kubernetes only with deliberate storage, backup, restore, upgrade, and failure planning.
How do Docker Compose health checks map to Kubernetes?
Kubernetes separates startup, readiness, and liveness. Readiness controls traffic eligibility, liveness can trigger restarts, and startup protects slow-starting applications.
Can Docker Compose services be migrated one at a time?
Yes, when service discovery, state ownership, traffic paths, and rollback are explicit. Incremental migration is often safer than moving every service at once.
When can the old Docker Compose host be shut down?
After Kubernetes has passed agreed traffic, state, job, monitoring, deployment, backup, and rollback checks and the old host is no longer needed as a runtime or recovery dependency.
How should Docker volumes be handled during migration?
Classify each volume by data owner and recovery requirement. Map durable state to PVCs, object storage, managed services, or another deliberate storage target before cutover.
Does managed Kubernetes remove application migration work?
No. Managed Kubernetes reduces control-plane operations. The application team still owns state, probes, resources, configuration, secrets, networking, rollout, and recovery.