--- reviewers: - cdrage title: Translate a Docker Compose File to Kubernetes Resources content_type: task weight: 230 --- 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 [https://kompose.io/](https://kompose.io/). ## {{% heading "prerequisites" %}} {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} ## Install Kompose We have multiple ways to install Kompose. Our preferred method is downloading the binary from the latest GitHub release. {{< tabs name="install_ways" >}} {{% tab name="GitHub download" %}} Kompose is released via GitHub on a three-week cycle, you can see all current releases on the [GitHub release page](https://github.com/kubernetes/kompose/releases). ```sh # Linux curl -L https://github.com/kubernetes/kompose/releases/download/v1.34.0/kompose-linux-amd64 -o kompose # macOS curl -L https://github.com/kubernetes/kompose/releases/download/v1.34.0/kompose-darwin-amd64 -o kompose # Windows curl -L https://github.com/kubernetes/kompose/releases/download/v1.34.0/kompose-windows-amd64.exe -o kompose.exe chmod +x kompose sudo mv ./kompose /usr/local/bin/kompose ``` Alternatively, you can download the [tarball](https://github.com/kubernetes/kompose/releases). {{% /tab %}} {{% tab name="Build from source" %}} Installing using `go get` pulls from the master branch with the latest development changes. ```sh go get -u github.com/kubernetes/kompose ``` {{% /tab %}} {{% tab name="Homebrew (macOS)" %}} On macOS you can install the latest release via [Homebrew](https://brew.sh): ```bash brew install kompose ``` {{% /tab %}} {{< /tabs >}} ## Use Kompose In 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. ```yaml services: redis-leader: container_name: redis-leader image: redis ports: - "6379" redis-replica: container_name: redis-replica image: redis ports: - "6379" command: redis-server --replicaof redis-leader 6379 --dir /tmp web: container_name: web image: quay.io/kompose/web ports: - "8080:8080" environment: - GET_HOSTS_FROM=dns labels: kompose.service.type: LoadBalancer ``` 2. To convert the `docker-compose.yml` file to files that you can use with `kubectl`, run `kompose convert` and then `kubectl apply -f `. ```bash kompose convert ``` The output is similar to: ```none INFO Kubernetes file "redis-leader-service.yaml" created INFO Kubernetes file "redis-replica-service.yaml" created INFO Kubernetes file "web-tcp-service.yaml" created INFO Kubernetes file "redis-leader-deployment.yaml" created INFO Kubernetes file "redis-replica-deployment.yaml" created INFO Kubernetes file "web-deployment.yaml" created ``` ```bash kubectl apply -f web-tcp-service.yaml,redis-leader-service.yaml,redis-replica-service.yaml,web-deployment.yaml,redis-leader-deployment.yaml,redis-replica-deployment.yaml ``` The output is similar to: ```none deployment.apps/redis-leader created deployment.apps/redis-replica created deployment.apps/web created service/redis-leader created service/redis-replica created service/web-tcp created ``` Your deployments are running in Kubernetes. 3. Access your application. If you're already using `minikube` for your development process: ```bash minikube service web-tcp ``` Otherwise, let's look up what IP your service is using! ```sh kubectl describe svc web-tcp ``` ```none Name: web-tcp Namespace: default Labels: io.kompose.service=web-tcp Annotations: kompose.cmd: kompose convert kompose.service.type: LoadBalancer kompose.version: 1.33.0 (3ce457399) Selector: io.kompose.service=web Type: LoadBalancer IP Family Policy: SingleStack IP Families: IPv4 IP: 10.102.30.3 IPs: 10.102.30.3 Port: 8080 8080/TCP TargetPort: 8080/TCP NodePort: 8080 31624/TCP Endpoints: 10.244.0.5:8080 Session Affinity: None External Traffic Policy: Cluster Events: ``` If you're using a cloud provider, your IP will be listed next to `LoadBalancer Ingress`. ```sh curl http://192.0.2.89 ``` 4. Clean-up. After you are finished testing out the example application deployment, simply run the following command in your shell to delete the resources used. ```sh kubectl delete -f web-tcp-service.yaml,redis-leader-service.yaml,redis-replica-service.yaml,web-deployment.yaml,redis-leader-deployment.yaml,redis-replica-deployment.yaml ``` ## User Guide - CLI - [`kompose convert`](#kompose-convert) - Documentation - [Alternative Conversions](#alternative-conversions) - [Labels](#labels) - [Restart](#restart) - [Docker Compose Versions](#docker-compose-versions) 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 `kompose convert` example ```shell kompose --file docker-voting.yml convert ``` ```none WARN Unsupported key networks - ignoring WARN Unsupported key build - ignoring INFO Kubernetes file "worker-svc.yaml" created INFO Kubernetes file "db-svc.yaml" created INFO Kubernetes file "redis-svc.yaml" created INFO Kubernetes file "result-svc.yaml" created INFO Kubernetes file "vote-svc.yaml" created INFO Kubernetes file "redis-deployment.yaml" created INFO Kubernetes file "result-deployment.yaml" created INFO Kubernetes file "vote-deployment.yaml" created INFO Kubernetes file "worker-deployment.yaml" created INFO Kubernetes file "db-deployment.yaml" created ``` ```shell ls ``` ```none db-deployment.yaml docker-compose.yml docker-gitlab.yml redis-deployment.yaml result-deployment.yaml vote-deployment.yaml worker-deployment.yaml 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: ```shell kompose -f docker-compose.yml -f docker-guestbook.yml convert ``` ```none INFO Kubernetes file "frontend-service.yaml" created INFO Kubernetes file "mlbparks-service.yaml" created INFO Kubernetes file "mongodb-service.yaml" created INFO Kubernetes file "redis-master-service.yaml" created INFO Kubernetes file "redis-slave-service.yaml" created INFO Kubernetes file "frontend-deployment.yaml" created INFO Kubernetes file "mlbparks-deployment.yaml" created INFO Kubernetes file "mongodb-deployment.yaml" created INFO Kubernetes file "mongodb-claim0-persistentvolumeclaim.yaml" created INFO Kubernetes file "redis-master-deployment.yaml" created INFO Kubernetes file "redis-slave-deployment.yaml" created ``` ```shell ls ``` ```none mlbparks-deployment.yaml mongodb-service.yaml redis-slave-service.jsonmlbparks-service.yaml frontend-deployment.yaml mongodb-claim0-persistentvolumeclaim.yaml redis-master-service.yaml frontend-service.yaml mongodb-deployment.yaml redis-slave-deployment.yaml redis-master-deployment.yaml ``` When multiple docker-compose files are provided the configuration is merged. Any configuration that is common will be overridden by subsequent file. ### OpenShift `kompose convert` example ```sh kompose --provider openshift --file docker-voting.yml convert ``` ```none WARN [worker] Service cannot be created because of missing port. INFO OpenShift file "vote-service.yaml" created INFO OpenShift file "db-service.yaml" created INFO OpenShift file "redis-service.yaml" created INFO OpenShift file "result-service.yaml" created INFO OpenShift file "vote-deploymentconfig.yaml" created INFO OpenShift file "vote-imagestream.yaml" created INFO OpenShift file "worker-deploymentconfig.yaml" created INFO OpenShift file "worker-imagestream.yaml" created INFO OpenShift file "db-deploymentconfig.yaml" created INFO OpenShift file "db-imagestream.yaml" created INFO OpenShift file "redis-deploymentconfig.yaml" created INFO OpenShift file "redis-imagestream.yaml" created INFO OpenShift file "result-deploymentconfig.yaml" created 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. ```sh kompose --provider openshift --file buildconfig/docker-compose.yml convert ``` ```none WARN [foo] Service cannot be created because of missing port. INFO OpenShift Buildconfig using git@github.com:rtnpro/kompose.git::master as source. INFO OpenShift file "foo-deploymentconfig.yaml" created INFO OpenShift file "foo-imagestream.yaml" created 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 . {{< /note >}} ## Alternative Conversions The default `kompose` transformation will generate Kubernetes [Deployments](/docs/concepts/workloads/controllers/deployment/) and [Services](/docs/concepts/services-networking/service/), in yaml format. You have alternative option to generate json with `-j`. Also, you can alternatively generate [Replication Controllers](/docs/concepts/workloads/controllers/replicationcontroller/) objects, [Daemon Sets](/docs/concepts/workloads/controllers/daemonset/), or [Helm](https://github.com/helm/helm) charts. ```sh kompose convert -j INFO Kubernetes file "redis-svc.json" created INFO Kubernetes file "web-svc.json" created INFO Kubernetes file "redis-deployment.json" created INFO Kubernetes file "web-deployment.json" created ``` The `*-deployment.json` files contain the Deployment objects. ```sh kompose convert --replication-controller INFO Kubernetes file "redis-svc.yaml" created INFO Kubernetes file "web-svc.yaml" created INFO Kubernetes file "redis-replicationcontroller.yaml" created 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`. ```shell kompose convert --daemon-set INFO Kubernetes file "redis-svc.yaml" created INFO Kubernetes file "web-svc.yaml" created INFO Kubernetes file "redis-daemonset.yaml" created INFO Kubernetes file "web-daemonset.yaml" created ``` The `*-daemonset.yaml` files contain the DaemonSet objects. If you want to generate a Chart to be used with [Helm](https://github.com/kubernetes/helm) run: ```shell kompose convert -c ``` ```none INFO Kubernetes file "web-svc.yaml" created INFO Kubernetes file "redis-svc.yaml" created INFO Kubernetes file "web-deployment.yaml" created INFO Kubernetes file "redis-deployment.yaml" created chart created in "./docker-compose/" ``` ```shell tree docker-compose/ ``` ```none docker-compose ├── Chart.yaml ├── README.md └── templates ├── redis-deployment.yaml ├── redis-svc.yaml ├── web-deployment.yaml └── 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: ```yaml version: "2" services: nginx: image: nginx dockerfile: foobar build: ./foobar cap_add: - ALL container_name: foobar labels: 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: ```yaml version: "2" services: web: image: tuna/docker-counter23 ports: - "5000:5000" links: - redis labels: kompose.service.expose: "counter.example.com" redis: image: redis:3.0 ports: - "6379" ``` The currently supported options are: | Key | Value | |----------------------|-------------------------------------| | kompose.service.type | nodeport / clusterip / loadbalancer | | kompose.service.expose| true / hostname | {{< note >}} The `kompose.service.type` label should be defined with `ports` only, otherwise `kompose` will fail. {{< /note >}} ## 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` `restart` | object created | Pod `restartPolicy` | |----------------------------|-------------------|---------------------| | `""` | controller object | `Always` | | `always` | controller object | `Always` | | `on-failure` | Pod | `OnFailure` | | `no` | Pod | `Never` | {{< note >}} The controller object could be `deployment` or `replicationcontroller`. {{< /note >}} For example, the `pival` service will become pod down here. This container calculated value of `pi`. ```yaml version: '2' services: pival: image: perl command: ["perl", "-Mbignum=bpi", "-wle", "print bpi(2000)"] restart: "on-failure" ``` ### Warning about Deployment Configurations 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 (for example, `web_service`), then it will be replaced by `-` and the service name will be renamed accordingly (for example, `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](https://github.com/kubernetes/kompose/blob/master/docs/conversion.md) including a list of all incompatible Docker Compose keys.