Translate a Docker Compose File to Kubernetes Resources

What’s Kompose? It’s a conversion tool for all things compose (namely Docker Compose) to container orchestrators (Kubernetes or OpenShift).

More information can be found on the Kompose website at http://kompose.io.

Before you begin

You need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using minikube or you can use one of these Kubernetes playgrounds:

To check the version, enter kubectl version.

Install Kompose

We have multiple ways to install Kompose. Our preferred method is downloading the binary from the latest GitHub release.

Kompose is released via GitHub on a three-week cycle, you can see all current releases on the GitHub release page.

  1. # Linux
  2. curl -L https://github.com/kubernetes/kompose/releases/download/v1.21.0/kompose-linux-amd64 -o kompose
  4. # macOS
  5. curl -L https://github.com/kubernetes/kompose/releases/download/v1.21.0/kompose-darwin-amd64 -o kompose
  7. # Windows
  8. curl -L https://github.com/kubernetes/kompose/releases/download/v1.21.0/kompose-windows-amd64.exe -o kompose.exe
  10. chmod +x kompose
  11. sudo mv ./kompose /usr/local/bin/kompose

Alternatively, you can download the tarball.

Installing using go get pulls from the master branch with the latest development changes.

  1. go get -u github.com/kubernetes/kompose

Kompose is in EPEL CentOS repository. If you don’t have EPEL repository already installed and enabled you can do it by running sudo yum install epel-release

If you have EPEL enabled in your system, you can install Kompose like any other package.

  1. sudo yum -y install kompose

Kompose is in Fedora 24, 25 and 26 repositories. You can install it just like any other package.

  1. sudo dnf -y install kompose

On macOS you can install latest release via Homebrew:

  1. brew install kompose

Use Kompose

In just a few steps, we’ll take you from Docker Compose to Kubernetes. All you need is an existing docker-compose.yml file.

  1. Go to the directory containing your docker-compose.yml file. If you don’t have one, test using this one.

    1. version: "2"
    3. services:
    5.   redis-master:
    6.     image: k8s.gcr.io/redis:e2e
    7.     ports:
    8.       - "6379"
    10.   redis-slave:
    11.     image: gcr.io/google_samples/gb-redisslave:v3
    12.     ports:
    13.       - "6379"
    14.     environment:
    15.       - GET_HOSTS_FROM=dns
    17.   frontend:
    18.     image: gcr.io/google-samples/gb-frontend:v4
    19.     ports:
    20.       - "80:80"
    21.     environment:
    22.       - GET_HOSTS_FROM=dns
    23.     labels:
    24.       kompose.service.type: LoadBalancer

  2. Run the kompose up command to deploy to Kubernetes directly, or skip to the next step instead to generate a file to use with kubectl.

    1. $ kompose up
    2. We are going to create Kubernetes Deployments, Services and PersistentVolumeClaims for your Dockerized application.
    3. If you need different kind of resources, use the 'kompose convert' and 'kubectl apply -f' commands instead.
    5. INFO Successfully created Service: redis          
    6. INFO Successfully created Service: web            
    7. INFO Successfully created Deployment: redis       
    8. INFO Successfully created Deployment: web         
    10. Your application has been deployed to Kubernetes. You can run 'kubectl get deployment,svc,pods,pvc' for details.

  3. To convert the docker-compose.yml file to files that you can use with kubectl, run kompose convert and then kubectl apply -f <output file>.

    1. $ kompose convert                           
    2. INFO Kubernetes file "frontend-service.yaml" created         
    3. INFO Kubernetes file "redis-master-service.yaml" created     
    4. INFO Kubernetes file "redis-slave-service.yaml" created      
    5. INFO Kubernetes file "frontend-deployment.yaml" created      
    6. INFO Kubernetes file "redis-master-deployment.yaml" created  
    7. INFO Kubernetes file "redis-slave-deployment.yaml" created
    1. $ kubectl apply -f frontend-service.yaml,redis-master-service.yaml,redis-slave-service.yaml,frontend-deployment.yaml,redis-master-deployment.yaml,redis-slave-deployment.yaml
    2. service/frontend created
    3. service/redis-master created
    4. service/redis-slave created
    5. deployment.apps/frontend created
    6. deployment.apps/redis-master created
    7. deployment.apps/redis-slave created

    Your deployments are running in Kubernetes.

  4. Access your application.

    If you’re already using minikube for your development process:

    1. $ minikube service frontend

    Otherwise, let’s look up what IP your service is using!

    1. $ kubectl describe svc frontend
    2. Name:                   frontend
    3. Namespace:              default
    4. Labels:                 service=frontend
    5. Selector:               service=frontend
    6. Type:                   LoadBalancer
    7. IP:                     10.0.0.183
    8. LoadBalancer Ingress:   192.0.2.89
    9. Port:                   80      80/TCP
    10. NodePort:               80      31144/TCP
    11. Endpoints:              172.17.0.4:80
    12. Session Affinity:       None
    13. No events.

    If you’re using a cloud provider, your IP will be listed next to LoadBalancer Ingress.

    1. $ curl http://192.0.2.89

User Guide

Kompose has support for two providers: OpenShift and Kubernetes. You can choose a targeted provider using global option --provider. If no provider is specified, Kubernetes is set by default.

kompose convert

Kompose supports conversion of V1, V2, and V3 Docker Compose files into Kubernetes and OpenShift objects.

Kubernetes

  1. $ kompose --file docker-voting.yml convert
  2. WARN Unsupported key networks - ignoring
  3. WARN Unsupported key build - ignoring
  4. INFO Kubernetes file "worker-svc.yaml" created
  5. INFO Kubernetes file "db-svc.yaml" created
  6. INFO Kubernetes file "redis-svc.yaml" created
  7. INFO Kubernetes file "result-svc.yaml" created
  8. INFO Kubernetes file "vote-svc.yaml" created
  9. INFO Kubernetes file "redis-deployment.yaml" created
  10. INFO Kubernetes file "result-deployment.yaml" created
  11. INFO Kubernetes file "vote-deployment.yaml" created
  12. INFO Kubernetes file "worker-deployment.yaml" created
  13. INFO Kubernetes file "db-deployment.yaml" created
  15. $ ls
  16. db-deployment.yaml  docker-compose.yml         docker-gitlab.yml  redis-deployment.yaml  result-deployment.yaml  vote-deployment.yaml  worker-deployment.yaml
  17. db-svc.yaml         docker-voting.yml          redis-svc.yaml     result-svc.yaml        vote-svc.yaml           worker-svc.yaml

You can also provide multiple docker-compose files at the same time:

  1. $ kompose -f docker-compose.yml -f docker-guestbook.yml convert
  2. INFO Kubernetes file "frontend-service.yaml" created         
  3. INFO Kubernetes file "mlbparks-service.yaml" created         
  4. INFO Kubernetes file "mongodb-service.yaml" created          
  5. INFO Kubernetes file "redis-master-service.yaml" created     
  6. INFO Kubernetes file "redis-slave-service.yaml" created      
  7. INFO Kubernetes file "frontend-deployment.yaml" created      
  8. INFO Kubernetes file "mlbparks-deployment.yaml" created      
  9. INFO Kubernetes file "mongodb-deployment.yaml" created       
  10. INFO Kubernetes file "mongodb-claim0-persistentvolumeclaim.yaml" created
  11. INFO Kubernetes file "redis-master-deployment.yaml" created  
  12. INFO Kubernetes file "redis-slave-deployment.yaml" created   
  14. $ ls
  15. mlbparks-deployment.yaml  mongodb-service.yaml                       redis-slave-service.jsonmlbparks-service.yaml  
  16. frontend-deployment.yaml  mongodb-claim0-persistentvolumeclaim.yaml  redis-master-service.yaml
  17. frontend-service.yaml     mongodb-deployment.yaml                    redis-slave-deployment.yaml
  18. redis-master-deployment.yaml

When multiple docker-compose files are provided the configuration is merged. Any configuration that is common will be over ridden by subsequent file.

OpenShift

  1. $ kompose --provider openshift --file docker-voting.yml convert
  2. WARN [worker] Service cannot be created because of missing port.
  3. INFO OpenShift file "vote-service.yaml" created             
  4. INFO OpenShift file "db-service.yaml" created               
  5. INFO OpenShift file "redis-service.yaml" created            
  6. INFO OpenShift file "result-service.yaml" created           
  7. INFO OpenShift file "vote-deploymentconfig.yaml" created    
  8. INFO OpenShift file "vote-imagestream.yaml" created         
  9. INFO OpenShift file "worker-deploymentconfig.yaml" created  
  10. INFO OpenShift file "worker-imagestream.yaml" created       
  11. INFO OpenShift file "db-deploymentconfig.yaml" created      
  12. INFO OpenShift file "db-imagestream.yaml" created           
  13. INFO OpenShift file "redis-deploymentconfig.yaml" created   
  14. INFO OpenShift file "redis-imagestream.yaml" created        
  15. INFO OpenShift file "result-deploymentconfig.yaml" created  
  16. INFO OpenShift file "result-imagestream.yaml" created

It also supports creating buildconfig for build directive in a service. By default, it uses the remote repo for the current git branch as the source repo, and the current branch as the source branch for the build. You can specify a different source repo and branch using --build-repo and --build-branch options respectively.

  1. $ kompose --provider openshift --file buildconfig/docker-compose.yml convert
  2. WARN [foo] Service cannot be created because of missing port.
  3. INFO OpenShift Buildconfig using git@github.com:rtnpro/kompose.git::master as source.
  4. INFO OpenShift file "foo-deploymentconfig.yaml" created     
  5. INFO OpenShift file "foo-imagestream.yaml" created          
  6. INFO OpenShift file "foo-buildconfig.yaml" created

Note: If you are manually pushing the OpenShift artifacts using oc create -f, you need to ensure that you push the imagestream artifact before the buildconfig artifact, to workaround this OpenShift issue: https://github.com/openshift/origin/issues/4518 .

kompose up

Kompose supports a straightforward way to deploy your “composed” application to Kubernetes or OpenShift via kompose up.

Kubernetes

  1. $ kompose --file ./examples/docker-guestbook.yml up
  2. We are going to create Kubernetes deployments and services for your Dockerized application.
  3. If you need different kind of resources, use the 'kompose convert' and 'kubectl apply -f' commands instead.
  5. INFO Successfully created service: redis-master   
  6. INFO Successfully created service: redis-slave    
  7. INFO Successfully created service: frontend       
  8. INFO Successfully created deployment: redis-master
  9. INFO Successfully created deployment: redis-slave
  10. INFO Successfully created deployment: frontend    
  12. Your application has been deployed to Kubernetes. You can run 'kubectl get deployment,svc,pods' for details.
  14. $ kubectl get deployment,svc,pods
  15. NAME                                              DESIRED       CURRENT       UP-TO-DATE   AVAILABLE   AGE
  16. deployment.extensions/frontend                    1             1             1            1           4m
  17. deployment.extensions/redis-master                1             1             1            1           4m
  18. deployment.extensions/redis-slave                 1             1             1            1           4m
  20. NAME                         TYPE               CLUSTER-IP    EXTERNAL-IP   PORT(S)      AGE
  21. service/frontend             ClusterIP          10.0.174.12   <none>        80/TCP       4m
  22. service/kubernetes           ClusterIP          10.0.0.1      <none>        443/TCP      13d
  23. service/redis-master         ClusterIP          10.0.202.43   <none>        6379/TCP     4m
  24. service/redis-slave          ClusterIP          10.0.1.85     <none>        6379/TCP     4m
  26. NAME                                READY         STATUS        RESTARTS     AGE
  27. pod/frontend-2768218532-cs5t5       1/1           Running       0            4m
  28. pod/redis-master-1432129712-63jn8   1/1           Running       0            4m
  29. pod/redis-slave-2504961300-nve7b    1/1           Running       0            4m

Note:

  • You must have a running Kubernetes cluster with a pre-configured kubectl context.
  • Only deployments and services are generated and deployed to Kubernetes. If you need different kind of resources, use the kompose convert and kubectl apply -f commands instead.

OpenShift

  1. $ kompose --file ./examples/docker-guestbook.yml --provider openshift up
  2. We are going to create OpenShift DeploymentConfigs and Services for your Dockerized application.
  3. If you need different kind of resources, use the 'kompose convert' and 'oc create -f' commands instead.
  5. INFO Successfully created service: redis-slave    
  6. INFO Successfully created service: frontend       
  7. INFO Successfully created service: redis-master   
  8. INFO Successfully created deployment: redis-slave
  9. INFO Successfully created ImageStream: redis-slave
  10. INFO Successfully created deployment: frontend    
  11. INFO Successfully created ImageStream: frontend   
  12. INFO Successfully created deployment: redis-master
  13. INFO Successfully created ImageStream: redis-master
  15. Your application has been deployed to OpenShift. You can run 'oc get dc,svc,is' for details.
  17. $ oc get dc,svc,is
  18. NAME               REVISION                              DESIRED       CURRENT    TRIGGERED BY
  19. dc/frontend        0                                     1             0          config,image(frontend:v4)
  20. dc/redis-master    0                                     1             0          config,image(redis-master:e2e)
  21. dc/redis-slave     0                                     1             0          config,image(redis-slave:v1)
  22. NAME               CLUSTER-IP                            EXTERNAL-IP   PORT(S)    AGE
  23. svc/frontend       172.30.46.64                          <none>        80/TCP     8s
  24. svc/redis-master   172.30.144.56                         <none>        6379/TCP   8s
  25. svc/redis-slave    172.30.75.245                         <none>        6379/TCP   8s
  26. NAME               DOCKER REPO                           TAGS          UPDATED
  27. is/frontend        172.30.12.200:5000/fff/frontend                     
  28. is/redis-master    172.30.12.200:5000/fff/redis-master                 
  29. is/redis-slave     172.30.12.200:5000/fff/redis-slave    v1

Note:

  • You must have a running OpenShift cluster with a pre-configured oc context (oc login)

kompose down

Once you have deployed “composed” application to Kubernetes, $ kompose down will help you to take the application out by deleting its deployments and services. If you need to remove other resources, use the ‘kubectl’ command.

  1. $ kompose --file docker-guestbook.yml down
  2. INFO Successfully deleted service: redis-master   
  3. INFO Successfully deleted deployment: redis-master
  4. INFO Successfully deleted service: redis-slave    
  5. INFO Successfully deleted deployment: redis-slave
  6. INFO Successfully deleted service: frontend       
  7. INFO Successfully deleted deployment: frontend

Note:

  • You must have a running Kubernetes cluster with a pre-configured kubectl context.

Build and Push Docker Images

Kompose supports both building and pushing Docker images. When using the build key within your Docker Compose file, your image will:

  • Automatically be built with Docker using the image key specified within your file
  • Be pushed to the correct Docker repository using local credentials (located at .docker/config)

Using an example Docker Compose file:

  1. version: "2"
  3. services:
  4.     foo:
  5.         build: "./build"
  6.         image: docker.io/foo/bar

Using kompose up with a build key:

  1. $ kompose up
  2. INFO Build key detected. Attempting to build and push image 'docker.io/foo/bar'
  3. INFO Building image 'docker.io/foo/bar' from directory 'build'
  4. INFO Image 'docker.io/foo/bar' from directory 'build' built successfully
  5. INFO Pushing image 'foo/bar:latest' to registry 'docker.io'
  6. INFO Attempting authentication credentials 'https://index.docker.io/v1/
  7. INFO Successfully pushed image 'foo/bar:latest' to registry 'docker.io'
  8. INFO We are going to create Kubernetes Deployments, Services and PersistentVolumeClaims for your Dockerized application. If you need different kind of resources, use the 'kompose convert' and 'kubectl apply -f' commands instead.
  10. INFO Deploying application in "default" namespace
  11. INFO Successfully created Service: foo            
  12. INFO Successfully created Deployment: foo         
  14. Your application has been deployed to Kubernetes. You can run 'kubectl get deployment,svc,pods,pvc' for details.

In order to disable the functionality, or choose to use BuildConfig generation (with OpenShift) --build (local|build-config|none) can be passed.

  1. # Disable building/pushing Docker images
  2. $ kompose up --build none
  4. # Generate Build Config artifacts for OpenShift
  5. $ kompose up --provider openshift --build build-config

Alternative Conversions

The default kompose transformation will generate Kubernetes Deployments and Services, in yaml format. You have alternative option to generate json with -j. Also, you can alternatively generate Replication Controllers objects, Daemon Sets, or Helm charts.

  1. $ kompose convert -j
  2. INFO Kubernetes file "redis-svc.json" created
  3. INFO Kubernetes file "web-svc.json" created
  4. INFO Kubernetes file "redis-deployment.json" created
  5. INFO Kubernetes file "web-deployment.json" created

The *-deployment.json files contain the Deployment objects.

  1. $ kompose convert --replication-controller
  2. INFO Kubernetes file "redis-svc.yaml" created
  3. INFO Kubernetes file "web-svc.yaml" created
  4. INFO Kubernetes file "redis-replicationcontroller.yaml" created
  5. INFO Kubernetes file "web-replicationcontroller.yaml" created

The *-replicationcontroller.yaml files contain the Replication Controller objects. If you want to specify replicas (default is 1), use --replicas flag: $ kompose convert --replication-controller --replicas 3

  1. $ kompose convert --daemon-set
  2. INFO Kubernetes file "redis-svc.yaml" created
  3. INFO Kubernetes file "web-svc.yaml" created
  4. INFO Kubernetes file "redis-daemonset.yaml" created
  5. INFO Kubernetes file "web-daemonset.yaml" created

The *-daemonset.yaml files contain the Daemon Set objects

If you want to generate a Chart to be used with Helm simply do:

  1. $ kompose convert -c
  2. INFO Kubernetes file "web-svc.yaml" created
  3. INFO Kubernetes file "redis-svc.yaml" created
  4. INFO Kubernetes file "web-deployment.yaml" created
  5. INFO Kubernetes file "redis-deployment.yaml" created
  6. chart created in "./docker-compose/"
  8. $ tree docker-compose/
  9. docker-compose
  10. ├── Chart.yaml
  11. ├── README.md
  12. └── templates
  13.     ├── redis-deployment.yaml
  14.     ├── redis-svc.yaml
  15.     ├── web-deployment.yaml
  16.     └── web-svc.yaml

The chart structure is aimed at providing a skeleton for building your Helm charts.

Labels

kompose supports Kompose-specific labels within the docker-compose.yml file in order to explicitly define a service’s behavior upon conversion.

  • kompose.service.type defines the type of service to be created.

For example:

  1. version: "2"
  2. services:
  3.   nginx:
  4.     image: nginx
  5.     dockerfile: foobar
  6.     build: ./foobar
  7.     cap_add:
  8.       - ALL
  9.     container_name: foobar
  10.     labels:
  11.       kompose.service.type: nodeport
  • kompose.service.expose defines if the service needs to be made accessible from outside the cluster or not. If the value is set to “true”, the provider sets the endpoint automatically, and for any other value, the value is set as the hostname. If multiple ports are defined in a service, the first one is chosen to be the exposed.
    • For the Kubernetes provider, an ingress resource is created and it is assumed that an ingress controller has already been configured.
    • For the OpenShift provider, a route is created.

For example:

  1. version: "2"
  2. services:
  3.   web:
  4.     image: tuna/docker-counter23
  5.     ports:
  6.      - "5000:5000"
  7.     links:
  8.      - redis
  9.     labels:
  10.       kompose.service.expose: "counter.example.com"
  11.   redis:
  12.     image: redis:3.0
  13.     ports:
  14.      - "6379"

The currently supported options are:

KeyValue
kompose.service.typenodeport / clusterip / loadbalancer
kompose.service.exposetrue / hostname

Note: The kompose.service.type label should be defined with ports only, otherwise kompose will fail.

Restart

If you want to create normal pods without controllers you can use restart construct of docker-compose to define that. Follow table below to see what happens on the restart value.

docker-compose restartobject createdPod restartPolicy
“”controller objectAlways
alwayscontroller objectAlways
on-failurePodOnFailure
noPodNever

Note: The controller object could be deployment or replicationcontroller, etc.

For example, the pival service will become pod down here. This container calculated value of pi.

  1. version: '2'
  3. services:
  4.   pival:
  5.     image: perl
  6.     command: ["perl",  "-Mbignum=bpi", "-wle", "print bpi(2000)"]
  7.     restart: "on-failure"

Warning about Deployment Config’s

If the Docker Compose file has a volume specified for a service, the Deployment (Kubernetes) or DeploymentConfig (OpenShift) strategy is changed to “Recreate” instead of “RollingUpdate” (default). This is done to avoid multiple instances of a service from accessing a volume at the same time.

If the Docker Compose file has service name with _ in it (eg.web_service), then it will be replaced by - and the service name will be renamed accordingly (eg.web-service). Kompose does this because “Kubernetes” doesn’t allow _ in object name.

Please note that changing service name might break some docker-compose files.

Docker Compose Versions

Kompose supports Docker Compose versions: 1, 2 and 3. We have limited support on versions 2.1 and 3.2 due to their experimental nature.

A full list on compatibility between all three versions is listed in our conversion document including a list of all incompatible Docker Compose keys.