Why Migrate to Kubernetes from Docker Compose?

Is migrating your orchestration tool from Docker Compose to Kubernetes a must? It is not, but if you have been running applications with Compose for a while, you may be starting to discover limitations that the simpler Compose model can’t handle. 

If you have never used Docker Compose, it’s a framework that provides an application and environmental definition for your containerized application in a single YAML file. This file will define the container images required, dependencies, networking specifications, and so on.

Docker Compose still does have some advantages over Kubernetes, but these are primarily due to its simplicity. The learning curve is not as steep. It makes deploying microservice applications easy. A single YAML file and one command can correctly configure your cloud environment and deploy your containers. 

This simplicity is also the thing that limits Docker Compose. Compose runs on a single host or cluster. Unlike Kubernetes, multi-cluster or even multi-cloud deployments are not an option. This should also tell you that scaling Compose also has limitations.  If you are using Kubernetes on a public cloud service like AWS, Microsoft Azure, or GCP, you can take advantage of a wide range of Kubernetes integrations that are not available to Compose users. 

Another issue with Docker Compose application is that the server running your application is a single point of failure. In a rather un-cloudlike manner, it must be kept running to keep the application running. Kubernetes is typically run with multiple nodes (servers) and can distribute and maintain multiple instances of a microservice across nodes.  This means that if one node fails, Kubernetes can assure continuity by deploying additional instances to any of the remaining nodes.

Still, I should say that if you are happy running Compose, then carry on; there is nothing inherently wrong with the tool. Just a couple of years ago, having your application development and management firmly embedded in the Docker ecosystem looked like a safe and sensible decision.  The company had truly revolutionized how applications were being run, and Docker containers were the new kid on the block that everyone wanted to get to know. Unfortunately, Docker’s domination of all things container started to fade with the arrival of Kubernetes, and as Docker’s developmental velocity slowed, Kubernetes became the leader in orchestration tools.

Migrating from Docker Compose to Kubernetes

The way that Compose and Kubernetes work are understandably different, and it might seem that this would make migrating from one to the other an ordeal.  Surprisingly, the oh so cleverly named Kompose tool makes this process remarkably easy. If, for example, you had a three-tier microservice application defined in your single docker-compose.yaml, Kompose would split that into .yaml files for each service to provide the Deployment and Service definitions that Kubernetes would require.

One of the most common concerns when migrating to Kubernetes from Docker Compose is the very different approach to networking.  Because Compose can create a single local network on the single host machine running your application, any container within the local network could connect to, for example, the local mariaDB instance with a hostname mariadb and port assignment of 8080 at http://mariadb:8080. Anything external to the local network would need to know the MariaDB container’s IP address.

Because Kubernetes typically runs on multiple nodes, networking functions differently. In Kubernetes, the Service allows communication between containers on the same or different nodes in a cluster.  Continuing with the example above, the MariaDB container definition would be converted into a Deployment and a Service. The Deployment defines the environmental considerations of deploying MariaDB to the cluster, and the Service is what Kubernetes uses to enable inter-container communication across the cluster. Even though the structure of the .yaml file differs, Kompose can define the service as mariadb and assign port 8080 so that a MariaDB container can still be reached at http://mariadb:8080. As a result, no networking changes should be needed when migrating from Docker Compose to Kubernetes.

Using Kompose to Migrate Your Docker Compose File

Once you’ve downloaded Kompose and navigated to your docker-compose.yml directory, running kompose convert and then kubectl apply -f {output_file} to convert the single docker-compose.yml to several Kubernetes configuration files. Running kubectl apply -f {config} will then launch your newly transformed application on your Kubernetes cluster.

While the few simple steps just described should get your Docker Compose application running on a Kubernetes cluster, life is rarely simple. Depending on the configuration and complexity of your application, additional troubleshooting may be necessary.  

Now that you are running on Kubernetes, it is good to check that access management and secrets continue to function correctly.  Even though Kompose will have enabled network communications, more performant networking solutions are available in Kubernetes, which may be a time to consider implementing them.

In some cases, developers will actually continue to use the single docker-compose.yaml to provide their application specification and use Kompose to translate the configuration over to a production environment. If your Kompose transformation was a one-way trip, it might be time to incorporate the new Kubernetes .yaml configuration files into a CI/CD process.


While the Docker ecosystem integration or simplicity of orchestrating your container app may have brought you to Docker Compose, transitioning over to Kubernetes will provide you with a much more performant orchestration engine. Your application will experience the benefits of being easier to manage, more scalable, more resilient, and much more.