From 4200987d9cc1036b54a446633c4fe72c33d68d3e Mon Sep 17 00:00:00 2001 From: Charlie Drage Date: Thu, 15 Jun 2017 15:46:36 -0400 Subject: [PATCH] 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 --- docs/user-guide.md | 145 +++++++++++++++++++++++++++++---------------- 1 file changed, 95 insertions(+), 50 deletions(-) diff --git a/docs/user-guide.md b/docs/user-guide.md index a889dd34b2..8e6c4a0ff4 100644 --- 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,20 +15,20 @@ 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 @@ -35,15 +36,15 @@ 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,12 +238,56 @@ 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: + +```yaml +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` 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 @@ -250,18 +295,18 @@ 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. \ No newline at end of file +Please note that changing service name might break some `docker-compose` files.