Add build/push instructions to user guide

Adds a user guide on how to use the build/push functionality of Docker images to the user guide. I also do minor changes such as removing `$ ` in the CLI examples, as it's easier to copy and paste without the `$ ` there (when double clicking). I've also changed the `console` yaml indicitors to `sh` since it doesn't matter / it's aliased, see: https://github.com/github/linguist/blob/master/lib/linguist/languages.yml
kubernetes · Jun 15, 2017 · 530f320 · 530f320
1 parent f823a22
commit 530f320
Showing 1 changed file with 95 additions and 50 deletions.
diff --git a/docs/user-guide.md b/docs/user-guide.md
@@ -1,11 +1,12 @@
 # User Guide
 
 - [Usage](#user-guide)
-  * [Kompose convert](#kompose-convert)
-  * [Kompose up](#kompose-up)
-  * [Kompose down](#kompose-down)
-- [Alternate formats](#alternate-formats)
-- [Unsupported docker-compose configuration options](#unsupported-docker-compose-configuration-options)
+  * [`kompose convert`](#kompose-convert)
+  * [`kompose up`](#kompose-up)
+  * [`kompose down`](#kompose-down)
+- [Build and Pushing Images](#build-and-pushing-images)
+- [Alternate Formats](#alternate-formats)
+- [Unsupported Docker Compose Configuration Options](#unsupported-docker-compose-configuration-options)
 
 
 Kompose has support for two providers: OpenShift and Kubernetes.
@@ -14,36 +15,36 @@ By setting environment variable `PROVIDER` you can permanently switch to OpenShi
 If no provider is specified Kubernetes is default provider.
 
 
-## Kompose convert
+## `kompose convert`
 
 Currently Kompose supports to transform either Docker Compose file (both of v1 and v2) and [experimental Distributed Application Bundles](https://blog.docker.com/2016/06/docker-app-bundle/) into Kubernetes and OpenShift objects.
 There is a couple of sample files in the `examples/` directory for testing.
 You will convert the compose or dab file to Kubernetes or OpenShift objects with `kompose convert`.
 
 ### Kubernetes
-```console
-$ cd examples/
+```sh
+cd examples/
 
-$ ls
+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
 INFO Kubernetes file "redisio-svc.yaml" created
 INFO Kubernetes file "gitlab-svc.yaml" created
 INFO Kubernetes file "postgresql-svc.yaml" created
 INFO Kubernetes file "gitlab-deployment.yaml" created
 INFO Kubernetes file "postgresql-deployment.yaml" created
 INFO Kubernetes file "redisio-deployment.yaml" created
 
-$ ls *.yaml
+ls *.yaml
 gitlab-deployment.yaml  postgresql-deployment.yaml  redis-deployment.yaml    redisio-svc.yaml  web-deployment.yaml
 gitlab-svc.yaml         postgresql-svc.yaml         redisio-deployment.yaml  redis-svc.yaml    web-svc.yaml
 ```
 
 You can try with a Docker Compose version 2 like this:
 
-```console
-$ kompose --file docker-voting.yml convert
+```sh
+kompose --file docker-voting.yml convert
 WARN Unsupported key networks - ignoring
 WARN Unsupported key build - ignoring
 INFO Kubernetes file "worker-svc.yaml" created
@@ -57,15 +58,15 @@ INFO Kubernetes file "vote-deployment.yaml" created
 INFO Kubernetes file "worker-deployment.yaml" created
 INFO Kubernetes file "db-deployment.yaml" created
 
-$ ls
+ls
 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-compose-bundle.dab  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:
 
-```console
-$ kompose -f docker-compose.yml -f docker-guestbook.yml convert
+```sh
+kompose -f docker-compose.yml -f docker-guestbook.yml convert
 INFO Kubernetes file "frontend-service.yaml" created         
 INFO Kubernetes file "mlbparks-service.yaml" created         
 INFO Kubernetes file "mongodb-service.yaml" created          
@@ -78,7 +79,7 @@ INFO Kubernetes file "mongodb-claim0-persistentvolumeclaim.yaml" created
 INFO Kubernetes file "redis-master-deployment.yaml" created  
 INFO Kubernetes file "redis-slave-deployment.yaml" created   
 
-$ ls
+ls
 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
@@ -89,8 +90,8 @@ When multiple docker-compose files are provided the configuration is merged. Any
 
 Using `--bundle, --dab` to specify a DAB file as below:
 
-```console
-$ kompose --bundle docker-compose-bundle.dab convert
+```sh
+kompose --bundle docker-compose-bundle.dab convert
 WARN: Unsupported key networks - ignoring
 INFO Kubernetes file "redis-svc.yaml" created
 INFO Kubernetes file "web-svc.yaml" created
@@ -100,8 +101,8 @@ INFO Kubernetes file "redis-deployment.yaml" created
 
 ### OpenShift
 
-```console
-$ kompose --provider openshift --file docker-voting.yml convert
+```sh
+kompose --provider openshift --file docker-voting.yml convert
 WARN [worker] Service cannot be created because of missing port.
 INFO OpenShift file "vote-service.yaml" created             
 INFO OpenShift file "db-service.yaml" created               
@@ -120,8 +121,8 @@ INFO OpenShift file "result-imagestream.yaml" created
 ```
 
 In similar way you can convert DAB files to OpenShift.
-```console
-$ kompose --bundle docker-compose-bundle.dab --provider openshift convert
+```sh
+kompose --bundle docker-compose-bundle.dab --provider openshift convert
 WARN: Unsupported key networks - ignoring
 INFO OpenShift file "redis-svc.yaml" created
 INFO OpenShift file "web-svc.yaml" created
@@ -133,8 +134,8 @@ INFO OpenShift 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
+```sh
+kompose --provider openshift --file buildconfig/docker-compose.yml convert
 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     
@@ -144,14 +145,14 @@ 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 up`
 
 Kompose supports a straightforward way to deploy your "composed" application to Kubernetes or OpenShift via `kompose up`.
 
 
 ### Kubernetes
-```console
-$ kompose --file ./examples/docker-guestbook.yml up
+```sh
+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.
 
@@ -164,7 +165,7 @@ INFO Successfully created deployment: frontend
 
 Your application has been deployed to Kubernetes. You can run 'kubectl get deployment,svc,pods' for details.
 
-$ kubectl get deployment,svc,pods
+kubectl get deployment,svc,pods
 NAME                               DESIRED       CURRENT       UP-TO-DATE   AVAILABLE   AGE
 deploy/frontend                    1             1             1            1           4m
 deploy/redis-master                1             1             1            1           4m
@@ -186,7 +187,7 @@ Note:
 - 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.
 
 ### OpenShift
-```console
+```sh
 $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.
@@ -203,7 +204,7 @@ INFO Successfully created ImageStream: redis-master
 
 Your application has been deployed to OpenShift. You can run 'oc get dc,svc,is' for details.
 
-$ oc get dc,svc,is
+oc get dc,svc,is
 NAME               REVISION                              DESIRED       CURRENT    TRIGGERED BY
 dc/frontend        0                                     1             0          config,image(frontend:v4)
 dc/redis-master    0                                     1             0          config,image(redis-master:e2e)
@@ -221,12 +222,12 @@ 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
+## `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.
 
-```console
-$ kompose --file docker-guestbook.yml down
+```sh
+kompose --file docker-guestbook.yml down
 INFO Successfully deleted service: redis-master   
 INFO Successfully deleted deployment: redis-master
 INFO Successfully deleted service: redis-slave    
@@ -237,31 +238,75 @@ INFO Successfully deleted deployment: frontend
 Note:
 - You must have a running Kubernetes cluster with a pre-configured kubectl context.
 
-## Alternate formats
+## Building and Pushing 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 and pushed.
+
+Using an [example Docker Compose file](https://raw.githubusercontent.com/kubernetes-incubator/kompose/master/examples/buildconfig/docker-compose.yml):
+
+```yaml
+version: "2"
+
+services:
+    foo:
+        build: "./build"
+        image: docker.io/foo/bar
+```
+
+Using `kompose up` with a `build` key:
+
+```sh
+kompose up
+INFO Build key detected. Attempting to build and push image 'docker.io/foo/bar' 
+INFO Building image 'docker.io/foo/bar' from directory 'build' 
+INFO Image 'docker.io/foo/bar' from directory 'build' built successfully 
+INFO Pushing image 'foo/bar:latest' to registry 'docker.io' 
+INFO Attempting authentication credentials 'https://index.docker.io/v1/ 
+INFO Successfully pushed image 'foo/bar:latest' to registry 'docker.io' 
+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 create -f' commands instead. 
+ 
+INFO Deploying application in "default" namespace 
+INFO Successfully created Service: foo            
+INFO Successfully created Deployment: foo         
+
+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.
+
+```sh
+# Disable building/pushing Docker images
+kompose up --build none
+
+# Generate Build Config artifacts for OpenShift
+kompose up --provider openshift --build build-config
+```
+
+## Alternate Formats
 
 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 -j
+```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.
 
-```console
-$ kompose convert --replication-controller
+```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`
+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`
 
-```console
-$ kompose convert --daemon-set
+```sh
+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
@@ -272,15 +317,15 @@ 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 
+```sh
+kompose convert -c 
 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/"
 
-$ tree docker-compose/
+tree docker-compose/
 docker-compose
 ├── Chart.yaml
 ├── README.md
@@ -293,14 +338,14 @@ docker-compose
 
 The chart structure is aimed at providing a skeleton for building your Helm charts.
 
-## Unsupported docker-compose configuration options
+## Unsupported Docker Compose Configuration Options
 
 Currently `kompose` does not support some Docker Compose options, which are listed on the [conversion](/docs/conversion.md) document.
 
 For example:
 
-```console
-$ cat nginx.yml
+```sh
+cat nginx.yml
 nginx:
   image: nginx
   dockerfile: foobar
@@ -309,7 +354,7 @@ nginx:
     - ALL
   container_name: foobar
 
-$ kompose -f nginx.yml convert
+kompose -f nginx.yml convert
 WARN Unsupported key build - ignoring             
 WARN Unsupported key cap_add - ignoring           
 WARN Unsupported key dockerfile - ignoring
@@ -401,4 +446,4 @@ If the Docker Compose file has a volume specified for a service, the Deployment
 
 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.
+Please note that changing service name might break some `docker-compose` files.