Update Kompose documentation

Updates the page with new installation details as well as some updated
fixes (spelling errors, outdated information, etc.)

Author: cdrage

docs/tools/kompose/user-guide.md

@@ -14,45 +14,50 @@ 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.
 
+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.
 
 ## Use Case
 
 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
-$ 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
-WARN[0000]: Unsupported key networks - ignoring
+WARN: Unsupported key networks - ignoring
 file "redis-svc.yaml" created
 file "web-svc.yaml" created
 file "web-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
-wget https://github.com/kubernetes-incubator/kompose/releases/download/v0.1.2/kompose_linux-amd64.tar.gz
-tar -xvf kompose_linux-amd64.tar.gz --strip 1
-sudo mv kompose /usr/local/bin
+# Linux 
+curl -L https://github.com/kubernetes-incubator/kompose/releases/download/v0.5.0/kompose-linux-amd64 -o kompose
+
+# 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.
-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.
+Make the binary executable and move it to your PATH (e.g. `/usr/local/bin`)
 
+```sh
+chmod +x kompose
+sudo mv ./kompose /usr/local/bin/kompose
+```
 
 ## Kompose convert
 
@@ -67,7 +72,7 @@ $ cd examples/
 $ ls
 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 "gitlab-svc.yaml" created
 file "postgresql-svc.yaml" created
@@ -84,8 +89,8 @@ You can try with a Docker Compose version 2 like this:
 
 ```console
 $ kompose --file docker-voting.yml convert
-WARN[0000]: Unsupported key networks - ignoring
-WARN[0000]: Unsupported key build - ignoring
+WARN Unsupported key networks - ignoring
+WARN Unsupported key build - ignoring
 file "worker-svc.yaml" created
 file "db-svc.yaml" created
 file "redis-svc.yaml" created
@@ -131,7 +136,7 @@ Using `--bundle, --dab` to specify a DAB file as below:
 
 ```console
 $ kompose --bundle docker-compose-bundle.dab convert
-WARN[0000]: Unsupported key networks - ignoring
+WARN: Unsupported key networks - ignoring
 file "redis-svc.yaml" created
 file "web-svc.yaml" created
 file "web-deployment.yaml" created
@@ -142,44 +147,44 @@ file "redis-deployment.yaml" created
 
 ```console
 $ kompose --provider openshift --file docker-voting.yml convert
-WARN[0000] [worker] Service cannot be created because of missing port.
-INFO[0000] file "vote-service.yaml" created             
-INFO[0000] file "db-service.yaml" created               
-INFO[0000] file "redis-service.yaml" created            
-INFO[0000] file "result-service.yaml" created           
-INFO[0000] file "vote-deploymentconfig.yaml" created    
-INFO[0000] file "vote-imagestream.yaml" created         
-INFO[0000] file "worker-deploymentconfig.yaml" created  
-INFO[0000] file "worker-imagestream.yaml" created       
-INFO[0000] file "db-deploymentconfig.yaml" created      
-INFO[0000] file "db-imagestream.yaml" created           
-INFO[0000] file "redis-deploymentconfig.yaml" created   
-INFO[0000] file "redis-imagestream.yaml" created        
-INFO[0000] file "result-deploymentconfig.yaml" created  
-INFO[0000] file "result-imagestream.yaml" created  
+WARN [worker] Service cannot be created because of missing port.
+INFO file "vote-service.yaml" created             
+INFO file "db-service.yaml" created               
+INFO file "redis-service.yaml" created            
+INFO file "result-service.yaml" created           
+INFO file "vote-deploymentconfig.yaml" created    
+INFO file "vote-imagestream.yaml" created         
+INFO file "worker-deploymentconfig.yaml" created  
+INFO file "worker-imagestream.yaml" created       
+INFO file "db-deploymentconfig.yaml" created      
+INFO file "db-imagestream.yaml" created           
+INFO file "redis-deploymentconfig.yaml" created   
+INFO file "redis-imagestream.yaml" created        
+INFO file "result-deploymentconfig.yaml" created  
+INFO file "result-imagestream.yaml" created  
 ```
 
 In similar way you can convert DAB files to OpenShift.
-```console$
+```console
 $ kompose --bundle docker-compose-bundle.dab --provider openshift convert
-WARN[0000]: Unsupported key networks - ignoring
-INFO[0000] file "redis-svc.yaml" created
-INFO[0000] file "web-svc.yaml" created
-INFO[0000] file "web-deploymentconfig.yaml" created
-INFO[0000] file "web-imagestream.yaml" created           
-INFO[0000] file "redis-deploymentconfig.yaml" created
-INFO[0000] file "redis-imagestream.yaml" created
+WARN: Unsupported key networks - ignoring
+INFO file "redis-svc.yaml" created
+INFO file "web-svc.yaml" created
+INFO file "web-deploymentconfig.yaml" created
+INFO file "web-imagestream.yaml" created           
+INFO file "redis-deploymentconfig.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.
 
 ```console
-kompose --provider openshift --file buildconfig/docker-compose.yml convert
-WARN[0000] [foo] Service cannot be created because of missing port. 
-INFO[0000] Buildconfig using [email protected]:rtnpro/kompose.git::master as source. 
-INFO[0000] file "foo-deploymentconfig.yaml" created     
-INFO[0000] file "foo-imagestream.yaml" created          
-INFO[0000] file "foo-buildconfig.yaml" created 
+$ kompose --provider openshift --file buildconfig/docker-compose.yml convert
+WARN [foo] Service cannot be created because of missing port. 
+INFO Buildconfig using [email protected]:rtnpro/kompose.git::master as source. 
+INFO file "foo-deploymentconfig.yaml" created     
+INFO file "foo-imagestream.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 .
@@ -195,12 +200,12 @@ $ kompose --file ./examples/docker-guestbook.yml up
 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.
 
-INFO[0000] Successfully created service: redis-master   
-INFO[0000] Successfully created service: redis-slave    
-INFO[0000] Successfully created service: frontend       
-INFO[0001] Successfully created deployment: redis-master
-INFO[0001] Successfully created deployment: redis-slave
-INFO[0001] Successfully created deployment: frontend    
+INFO Successfully created service: redis-master   
+INFO Successfully created service: redis-slave    
+INFO Successfully created service: frontend       
+INFO Successfully created deployment: redis-master
+INFO Successfully created deployment: redis-slave
+INFO Successfully created deployment: frontend    
 
 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
 ```
 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 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.
 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[0000] Successfully created service: frontend       
-INFO[0000] Successfully created service: redis-master   
-INFO[0000] Successfully created deployment: redis-slave
-INFO[0000] Successfully created ImageStream: redis-slave
-INFO[0000] Successfully created deployment: frontend    
-INFO[0000] Successfully created ImageStream: frontend   
-INFO[0000] Successfully created deployment: redis-master
-INFO[0000] Successfully created ImageStream: redis-master
+INFO Successfully created service: redis-slave    
+INFO Successfully created service: frontend       
+INFO Successfully created service: redis-master   
+INFO Successfully created deployment: redis-slave
+INFO Successfully created ImageStream: redis-slave
+INFO Successfully created deployment: frontend    
+INFO Successfully created ImageStream: frontend   
+INFO Successfully created deployment: 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.
 
@@ -260,7 +264,6 @@ 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
@@ -269,12 +272,12 @@ Once you have deployed "composed" application to Kubernetes, `kompose down` will
 
 ```console
 $ kompose --file docker-guestbook.yml down
-INFO[0000] Successfully deleted service: redis-master   
-INFO[0004] Successfully deleted deployment: redis-master
-INFO[0004] Successfully deleted service: redis-slave    
-INFO[0008] Successfully deleted deployment: redis-slave
-INFO[0009] Successfully deleted service: frontend       
-INFO[0013] Successfully deleted deployment: frontend
+INFO Successfully deleted service: redis-master   
+INFO Successfully deleted deployment: redis-master
+INFO Successfully deleted service: redis-slave    
+INFO Successfully deleted deployment: redis-slave
+INFO Successfully deleted service: frontend       
+INFO Successfully deleted deployment: frontend
 ```
 Note:
 - 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.
 
 ```console
-$ kompose convert
-file "redis-svc.yaml" created
-file "web-svc.yaml" created
-file "redis-deployment.yaml" created
-file "web-deployment.yaml" created
+$ kompose convert -j
+file "redis-svc.json" created
+file "web-svc.json" created
+file "redis-deployment.json" created
+file "web-deployment.json" created
 ```
 The `*-deployment.json` files contain the Deployment objects.
 
 ```console
-$ kompose convert --rc
+$ kompose convert --rc 
 file "redis-svc.yaml" created
 file "web-svc.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`
 
 ```console
-$ kompose convert --ds
+$ kompose convert --ds 
 file "redis-svc.yaml" created
 file "web-svc.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:
 
 ```console
-$ kompose convert -c
+$ kompose convert -c 
 file "web-svc.yaml" created
 file "redis-svc.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
 
-Currently `kompose` does not support the following Docker Compose options.
-
-```
-"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"
-```
+Currently `kompose` does not support some Docker Compose options, which are listed on the [conversion](http://kompose.io/conversion/) document.
 
 For example:
 
@@ -356,9 +355,9 @@ nginx:
   container_name: foobar
 
 $ kompose -f nginx.yml convert
-WARN[0000] Unsupported key build - ignoring             
-WARN[0000] Unsupported key cap_add - ignoring           
-WARN[0000] Unsupported key dockerfile - ignoring
+WARN Unsupported key build - ignoring             
+WARN Unsupported key cap_add - ignoring           
+WARN Unsupported key dockerfile - ignoring
 ```
 
 ## 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.
 
-For e.g. `mariadb` service will become pod down here.
-
 ```yaml
-version: "2"
+version: '2'
 
 services:
-  mariadb:
-    image: centos/mariadb
-    restart: "no"
+  pival:
+    image: perl
+    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.