whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update Kompose documentation

Browse Source 
Updates the page with new installation details as well as some updated
fixes (spelling errors, outdated information, etc.)
This commit is contained in:
Charlie Drage
2017-04-20 13:45:00 -04:00
committed by Andrew Chen
parent 62d4745f0d
commit 8ff1959f16
1 changed files with 97 additions and 96 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/tools/kompose/user-guide.md
+97 -96
View File
@@ -14,6 +14,8 @@ redirect_from:
`kompose` is a tool to help users who are familiar with `docker-compose` move to **Kubernetes**. `kompose` takes a Docker Compose file and translates it into Kubernetes resources. `kompose` is a tool to help users who are familiar with `docker-compose` move to **Kubernetes**. `kompose` takes a Docker Compose file and translates it into Kubernetes resources.
More information about Kompose can be found on the official [http://kompose.io](http://kompose.io/) site.
`kompose` is a convenience tool to go from local Docker development to managing your application with Kubernetes. Transformation of the Docker Compose format to Kubernetes resources manifest may not be exact, but it helps tremendously when first deploying an application on Kubernetes. `kompose` is a convenience tool to go from local Docker development to managing your application with Kubernetes. Transformation of the Docker Compose format to Kubernetes resources manifest may not be exact, but it helps tremendously when first deploying an application on Kubernetes.
## Use Case ## Use Case
@@ -21,38 +23,41 @@ redirect_from:
If you have a Docker Compose `docker-compose.yml` or a Docker Distributed Application Bundle `docker-compose-bundle.dab` file, you can convert it into Kubernetes deployments and services like this: If you have a Docker Compose `docker-compose.yml` or a Docker Distributed Application Bundle `docker-compose-bundle.dab` file, you can convert it into Kubernetes deployments and services like this:
```console ```console
$ kompose --bundle docker-compose-bundle.dab convert
WARN[0000]: Unsupported key networks - ignoring
file "redis-svc.yaml" created
file "web-svc.yaml" created
file "web-deployment.yaml" created
file "redis-deployment.yaml" created
$ kompose -f docker-compose.yml convert $ kompose -f docker-compose.yml convert
WARN[0000]: Unsupported key networks - ignoring WARN: Unsupported key networks - ignoring
file "redis-svc.yaml" created file "redis-svc.yaml" created
file "web-svc.yaml" created file "web-svc.yaml" created
file "web-deployment.yaml" created file "web-deployment.yaml" created
file "redis-deployment.yaml" created file "redis-deployment.yaml" created
``` ```
## Installation ## Installation
Grab the latest [release](https://github.com/kubernetes-incubator/kompose/releases) for your OS, untar and extract the binary. We have multiple ways to install Kompose. Our prefered method is downloading the binary from the latest GitHub release.
### Linux ### GitHub release
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-incubator/kompose/releases).
The current release we use is `0.5.0`.
```sh ```sh
wget https://github.com/kubernetes-incubator/kompose/releases/download/v0.1.2/kompose_linux-amd64.tar.gz # Linux
tar -xvf kompose_linux-amd64.tar.gz --strip 1 curl -L https://github.com/kubernetes-incubator/kompose/releases/download/v0.5.0/kompose-linux-amd64 -o kompose
sudo mv kompose /usr/local/bin
# macOS
curl -L https://github.com/kubernetes-incubator/kompose/releases/download/v0.5.0/kompose-darwin-amd64 -o kompose
# Windows
curl -L https://github.com/kubernetes-incubator/kompose/releases/download/v0.5.0/kompose-windows-amd64.exe -o kompose.exe
``` ```
Kompose has support for two providers: OpenShift and Kubernetes. Make the binary executable and move it to your PATH (e.g. `/usr/local/bin`)
You can choose targeted provider either using global option `--provider`, or by setting environment variable `PROVIDER`.
By setting environment variable `PROVIDER` you can permanently switch to OpenShift provider without need to always specify `--provider openshift` option.
If no provider is specified Kubernetes is default provider.
```sh
chmod +x kompose
sudo mv ./kompose /usr/local/bin/kompose
```
## Kompose convert ## Kompose convert
@@ -67,7 +72,7 @@ $ cd examples/
$ ls $ ls
docker-compose.yml docker-compose-bundle.dab docker-gitlab.yml docker-voting.yml docker-compose.yml docker-compose-bundle.dab docker-gitlab.yml docker-voting.yml
$ kompose -f docker-gitlab.yml convert $ kompose -f docker-gitlab.yml convert
file "redisio-svc.yaml" created file "redisio-svc.yaml" created
file "gitlab-svc.yaml" created file "gitlab-svc.yaml" created
file "postgresql-svc.yaml" created file "postgresql-svc.yaml" created
@@ -84,8 +89,8 @@ You can try with a Docker Compose version 2 like this:
```console ```console
$ kompose --file docker-voting.yml convert $ kompose --file docker-voting.yml convert
WARN[0000]: Unsupported key networks - ignoring WARN Unsupported key networks - ignoring
WARN[0000]: Unsupported key build - ignoring WARN Unsupported key build - ignoring
file "worker-svc.yaml" created file "worker-svc.yaml" created
file "db-svc.yaml" created file "db-svc.yaml" created
file "redis-svc.yaml" created file "redis-svc.yaml" created
@@ -131,7 +136,7 @@ Using `--bundle, --dab` to specify a DAB file as below:
```console ```console
$ kompose --bundle docker-compose-bundle.dab convert $ kompose --bundle docker-compose-bundle.dab convert
WARN[0000]: Unsupported key networks - ignoring WARN: Unsupported key networks - ignoring
file "redis-svc.yaml" created file "redis-svc.yaml" created
file "web-svc.yaml" created file "web-svc.yaml" created
file "web-deployment.yaml" created file "web-deployment.yaml" created
@@ -142,44 +147,44 @@ file "redis-deployment.yaml" created
```console ```console
$ kompose --provider openshift --file docker-voting.yml convert $ kompose --provider openshift --file docker-voting.yml convert
WARN[0000] [worker] Service cannot be created because of missing port. WARN [worker] Service cannot be created because of missing port.
INFO[0000] file "vote-service.yaml" created INFO file "vote-service.yaml" created
INFO[0000] file "db-service.yaml" created INFO file "db-service.yaml" created
INFO[0000] file "redis-service.yaml" created INFO file "redis-service.yaml" created
INFO[0000] file "result-service.yaml" created INFO file "result-service.yaml" created
INFO[0000] file "vote-deploymentconfig.yaml" created INFO file "vote-deploymentconfig.yaml" created
INFO[0000] file "vote-imagestream.yaml" created INFO file "vote-imagestream.yaml" created
INFO[0000] file "worker-deploymentconfig.yaml" created INFO file "worker-deploymentconfig.yaml" created
INFO[0000] file "worker-imagestream.yaml" created INFO file "worker-imagestream.yaml" created
INFO[0000] file "db-deploymentconfig.yaml" created INFO file "db-deploymentconfig.yaml" created
INFO[0000] file "db-imagestream.yaml" created INFO file "db-imagestream.yaml" created
INFO[0000] file "redis-deploymentconfig.yaml" created INFO file "redis-deploymentconfig.yaml" created
INFO[0000] file "redis-imagestream.yaml" created INFO file "redis-imagestream.yaml" created
INFO[0000] file "result-deploymentconfig.yaml" created INFO file "result-deploymentconfig.yaml" created
INFO[0000] file "result-imagestream.yaml" created INFO file "result-imagestream.yaml" created
``` ```
In similar way you can convert DAB files to OpenShift. In similar way you can convert DAB files to OpenShift.
```console$ ```console
$ kompose --bundle docker-compose-bundle.dab --provider openshift convert $ kompose --bundle docker-compose-bundle.dab --provider openshift convert
WARN[0000]: Unsupported key networks - ignoring WARN: Unsupported key networks - ignoring
INFO[0000] file "redis-svc.yaml" created INFO file "redis-svc.yaml" created
INFO[0000] file "web-svc.yaml" created INFO file "web-svc.yaml" created
INFO[0000] file "web-deploymentconfig.yaml" created INFO file "web-deploymentconfig.yaml" created
INFO[0000] file "web-imagestream.yaml" created INFO file "web-imagestream.yaml" created
INFO[0000] file "redis-deploymentconfig.yaml" created INFO file "redis-deploymentconfig.yaml" created
INFO[0000] file "redis-imagestream.yaml" created INFO file "redis-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. 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.
```console ```console
kompose --provider openshift --file buildconfig/docker-compose.yml convert $ kompose --provider openshift --file buildconfig/docker-compose.yml convert
WARN[0000] [foo] Service cannot be created because of missing port. WARN [foo] Service cannot be created because of missing port.
INFO[0000] Buildconfig using git@github.com:rtnpro/kompose.git::master as source. INFO Buildconfig using git@github.com:rtnpro/kompose.git::master as source.
INFO[0000] file "foo-deploymentconfig.yaml" created INFO file "foo-deploymentconfig.yaml" created
INFO[0000] file "foo-imagestream.yaml" created INFO file "foo-imagestream.yaml" created
INFO[0000] file "foo-buildconfig.yaml" created INFO 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**: 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 .
@@ -195,12 +200,12 @@ $ kompose --file ./examples/docker-guestbook.yml up
We are going to create Kubernetes deployments and services for your Dockerized application. We are going to create Kubernetes deployments and services for your Dockerized application.
If you need different kind of resources, use the 'kompose convert' and 'kubectl create -f' commands instead. If you need different kind of resources, use the 'kompose convert' and 'kubectl create -f' commands instead.
INFO[0000] Successfully created service: redis-master INFO Successfully created service: redis-master
INFO[0000] Successfully created service: redis-slave INFO Successfully created service: redis-slave
INFO[0000] Successfully created service: frontend INFO Successfully created service: frontend
INFO[0001] Successfully created deployment: redis-master INFO Successfully created deployment: redis-master
INFO[0001] Successfully created deployment: redis-slave INFO Successfully created deployment: redis-slave
INFO[0001] Successfully created deployment: frontend INFO Successfully created deployment: frontend
Your application has been deployed to Kubernetes. You can run 'kubectl get deployment,svc,pods' for details. Your application has been deployed to Kubernetes. You can run 'kubectl get deployment,svc,pods' for details.
@@ -222,7 +227,6 @@ po/redis-master-1432129712-63jn8 1/1 Running 0 4m
po/redis-slave-2504961300-nve7b 1/1 Running 0 4m po/redis-slave-2504961300-nve7b 1/1 Running 0 4m
``` ```
Note: Note:
- You must have a running Kubernetes cluster with a pre-configured kubectl context. - 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 create -f' commands instead. - Only deployments and services are generated and deployed to Kubernetes. If you need different kind of resources, use the 'kompose convert' and 'kubectl create -f' commands instead.
@@ -232,15 +236,15 @@ $kompose --file ./examples/docker-guestbook.yml --provider openshift up
We are going to create OpenShift DeploymentConfigs and Services for your Dockerized application. We are going to create OpenShift DeploymentConfigs and Services for your Dockerized application.
If you need different kind of resources, use the 'kompose convert' and 'oc create -f' commands instead. If you need different kind of resources, use the 'kompose convert' and 'oc create -f' commands instead.
INFO[0000] Successfully created service: redis-slave INFO Successfully created service: redis-slave
INFO[0000] Successfully created service: frontend INFO Successfully created service: frontend
INFO[0000] Successfully created service: redis-master INFO Successfully created service: redis-master
INFO[0000] Successfully created deployment: redis-slave INFO Successfully created deployment: redis-slave
INFO[0000] Successfully created ImageStream: redis-slave INFO Successfully created ImageStream: redis-slave
INFO[0000] Successfully created deployment: frontend INFO Successfully created deployment: frontend
INFO[0000] Successfully created ImageStream: frontend INFO Successfully created ImageStream: frontend
INFO[0000] Successfully created deployment: redis-master INFO Successfully created deployment: redis-master
INFO[0000] Successfully created ImageStream: redis-master INFO Successfully created ImageStream: redis-master
Your application has been deployed to OpenShift. You can run 'oc get dc,svc,is' for details. Your application has been deployed to OpenShift. You can run 'oc get dc,svc,is' for details.
@@ -260,7 +264,6 @@ is/redis-slave 172.30.12.200:5000/fff/redis-slave v1
``` ```
Note: Note:
- You must have a running OpenShift cluster with a pre-configured `oc` context (`oc login`) - You must have a running OpenShift cluster with a pre-configured `oc` context (`oc login`)
## Kompose down ## Kompose down
@@ -269,12 +272,12 @@ Once you have deployed "composed" application to Kubernetes, `kompose down` will
```console ```console
$ kompose --file docker-guestbook.yml down $ kompose --file docker-guestbook.yml down
INFO[0000] Successfully deleted service: redis-master INFO Successfully deleted service: redis-master
INFO[0004] Successfully deleted deployment: redis-master INFO Successfully deleted deployment: redis-master
INFO[0004] Successfully deleted service: redis-slave INFO Successfully deleted service: redis-slave
INFO[0008] Successfully deleted deployment: redis-slave INFO Successfully deleted deployment: redis-slave
INFO[0009] Successfully deleted service: frontend INFO Successfully deleted service: frontend
INFO[0013] Successfully deleted deployment: frontend INFO Successfully deleted deployment: frontend
``` ```
Note: Note:
- You must have a running Kubernetes cluster with a pre-configured kubectl context. - You must have a running Kubernetes cluster with a pre-configured kubectl context.
@@ -284,16 +287,16 @@ Note:
The default `kompose` transformation will generate Kubernetes [Deployments](http://kubernetes.io/docs/user-guide/deployments/) and [Services](http://kubernetes.io/docs/user-guide/services/), in yaml format. You have alternative option to generate json with `-j`. Also, you can alternatively generate [Replication Controllers](http://kubernetes.io/docs/user-guide/replication-controller/) objects, [Deamon Sets](http://kubernetes.io/docs/admin/daemons/), or [Helm](https://github.com/helm/helm) charts. The default `kompose` transformation will generate Kubernetes [Deployments](http://kubernetes.io/docs/user-guide/deployments/) and [Services](http://kubernetes.io/docs/user-guide/services/), in yaml format. You have alternative option to generate json with `-j`. Also, you can alternatively generate [Replication Controllers](http://kubernetes.io/docs/user-guide/replication-controller/) objects, [Deamon Sets](http://kubernetes.io/docs/admin/daemons/), or [Helm](https://github.com/helm/helm) charts.
```console ```console
$ kompose convert $ kompose convert -j
file "redis-svc.yaml" created file "redis-svc.json" created
file "web-svc.yaml" created file "web-svc.json" created
file "redis-deployment.yaml" created file "redis-deployment.json" created
file "web-deployment.yaml" created file "web-deployment.json" created
``` ```
The `*-deployment.json` files contain the Deployment objects. The `*-deployment.json` files contain the Deployment objects.
```console ```console
$ kompose convert --rc $ kompose convert --rc
file "redis-svc.yaml" created file "redis-svc.yaml" created
file "web-svc.yaml" created file "web-svc.yaml" created
file "redis-rc.yaml" created file "redis-rc.yaml" created
@@ -303,7 +306,7 @@ file "web-rc.yaml" created
The `*-rc.yaml` files contain the Replication Controller objects. If you want to specify replicas (default is 1), use `--replicas` flag: `$ kompose convert --rc --replicas 3` The `*-rc.yaml` files contain the Replication Controller objects. If you want to specify replicas (default is 1), use `--replicas` flag: `$ kompose convert --rc --replicas 3`
```console ```console
$ kompose convert --ds $ kompose convert --ds
file "redis-svc.yaml" created file "redis-svc.yaml" created
file "web-svc.yaml" created file "web-svc.yaml" created
file "redis-daemonset.yaml" created file "redis-daemonset.yaml" created
@@ -315,7 +318,7 @@ The `*-daemonset.yaml` files contain the Daemon Set objects
If you want to generate a Chart to be used with [Helm](https://github.com/kubernetes/helm) simply do: If you want to generate a Chart to be used with [Helm](https://github.com/kubernetes/helm) simply do:
```console ```console
$ kompose convert -c $ kompose convert -c
file "web-svc.yaml" created file "web-svc.yaml" created
file "redis-svc.yaml" created file "redis-svc.yaml" created
file "web-deployment.yaml" created file "web-deployment.yaml" created
@@ -337,11 +340,7 @@ The chart structure is aimed at providing a skeleton for building your Helm char
## Unsupported docker-compose configuration options ## Unsupported docker-compose configuration options
Currently `kompose` does not support the following Docker Compose options. Currently `kompose` does not support some Docker Compose options, which are listed on the [conversion](http://kompose.io/conversion/) document.
```
"build", "cgroup_parent", "devices", "depends_on", "dns", "dns_search", "domainname", "env_file", "extends", "external_links", "extra_hosts", "hostname", "ipc", "logging", "mac_address", "mem_limit", "memswap_limit", "network_mode", "networks", "pid", "security_opt", "shm_size", "stop_signal", "volume_driver", "uts", "read_only", "stdin_open", "tty", "user", "ulimits", "dockerfile", "net"
```
For example: For example:
@@ -356,9 +355,9 @@ nginx:
container_name: foobar container_name: foobar
$ kompose -f nginx.yml convert $ kompose -f nginx.yml convert
WARN[0000] Unsupported key build - ignoring WARN Unsupported key build - ignoring
WARN[0000] Unsupported key cap_add - ignoring WARN Unsupported key cap_add - ignoring
WARN[0000] Unsupported key dockerfile - ignoring WARN Unsupported key dockerfile - ignoring
``` ```
## Labels ## Labels
@@ -427,13 +426,15 @@ If you want to create normal pods without controllers you can use `restart` cons
**Note**: controller object could be `deployment` or `replicationcontroller`, etc. **Note**: controller object could be `deployment` or `replicationcontroller`, etc.
For e.g. `mariadb` service will become pod down here.
```yaml ```yaml
version: "2" version: '2'
services: services:
mariadb: pival:
image: centos/mariadb image: perl
restart: "no" command: ["perl", "-Mbignum=bpi", "-wle", "print bpi(2000)"]
restart: "on-failure"
``` ```
#### Warning about DeploymentConfig
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.