diff --git a/docs/README.md b/docs/README.md index 3a1dfe22..48026300 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,7 +1,9 @@ # Kompose Documentation +* [Introduction](introduction.md) +* [Quick Start](quickstart.md) +* [User Guide](user-guide.md) * [Architecture](architecture.md) * [Conversion](conversion.md) * [Development](development.md) * [Setup](setup.md) -* [User Guide](user-guide.md) diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 00000000..04f3c70e --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,347 @@ +# Getting Started + +- [Minikube and Kompose](#minikube-and-kompose) +- [Minishift and Kompose](#minishift-and-kompose) +- [RHEL and Kompose](#rhel-and-kompose) + +This is how you'll get started with Kompose! + +There are two different guides depending on your container orchestrator. + +## Minikube and Kompose + +In this guide, we'll deploy a sample `docker-compose.yaml` file to a Kubernetes cluster. + +Requirements: + - [minikube](https://github.com/kubernetes/minikube) + - [kompose](https://github.com/kubernetes/kompose) + +__Start `minikube`:__ + +If you don't already have a Kubernetes cluster running, [minikube](https://github.com/kubernetes/minikube) is the best way to get started. + +```sh +$ minikube start +Starting local Kubernetes v1.7.5 cluster... +Starting VM... +Getting VM IP address... +Moving files into cluster... +Setting up certs... +Connecting to cluster... +Setting up kubeconfig... +Starting cluster components... +Kubectl is now configured to use the cluster +``` + +__Download an [example Docker Compose file](https://raw.githubusercontent.com/kubernetes/kompose/master/examples/docker-compose.yaml), or use your own:__ + +```sh +wget https://raw.githubusercontent.com/kubernetes/kompose/master/examples/docker-compose.yaml +``` + +__Convert your Docker Compose file to Kubernetes:__ + +Run `kompose convert` in the same directory as your `docker-compose.yaml` file. + +```sh +$ kompose convert +INFO Kubernetes file "frontend-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 "redis-master-deployment.yaml" created +INFO Kubernetes file "redis-slave-deployment.yaml" created +``` + +Alternatively, you can convert and deploy directly to Kubernetes with `kompose up`. + +```sh +$ kompose up +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 Successfully created Service: redis +INFO Successfully created Service: web +INFO Successfully created Deployment: redis +INFO Successfully created Deployment: web + +Your application has been deployed to Kubernetes. You can run 'kubectl get deployment,svc,pods,pvc' for details. +``` + + +__Access the newly deployed service:__ + +Now that your service has been deployed, let's access it. + +If you're using `minikube` you may access it via the `minikube service` command. + +```sh +$ minikube service frontend +``` + +Otherwise, use `kubectl` to see what IP the service is using: + +```sh +$ kubectl describe svc frontend +Name: frontend +Namespace: default +Labels: service=frontend +Selector: service=frontend +Type: LoadBalancer +IP: 10.0.0.183 +LoadBalancer Ingress: 123.45.67.89 +Port: 80 80/TCP +NodePort: 80 31144/TCP +Endpoints: 172.17.0.4:80 +Session Affinity: None +No events. + +``` + +Note: If you're using a cloud provider, your IP will be listed next to `LoadBalancer Ingress`. + +If you have yet to expose your service (for example, within GCE), use the command: + +```sh +kubectl expose deployment frontend --type="LoadBalancer" +``` + +To check functionality, you may also `curl` the URL. + +```sh +$ curl http://123.45.67.89 +``` + +## Minishift and Kompose + +In this guide, we'll deploy a sample `docker-compose.yaml` file to an OpenShift cluster. + +Requirements: + - [minishift](https://github.com/minishift/minishift) + - [kompose](https://github.com/kubernetes/kompose) + - An OpenShift route created + +__Note:__ The service will NOT be accessible until you create an OpenShift route with `oc expose`. You must also have a virtualization environment setup. By default, `minishift` uses KVM. + +__Start `minishift`:__ + +[Minishift](https://github.com/minishift/minishift) is a tool that helps run OpenShift locally using a single-node cluster inside of a VM. Similar to [minikube](https://github.com/kubernetes/minikube). + +```sh +$ minishift start +Starting local OpenShift cluster using 'kvm' hypervisor... +-- Checking OpenShift client ... OK +-- Checking Docker client ... OK +-- Checking Docker version ... OK +-- Checking for existing OpenShift container ... OK +... +``` + +__Download an [example Docker Compose file](https://raw.githubusercontent.com/kubernetes/kompose/master/examples/docker-compose.yaml), or use your own:__ + +```sh +wget https://raw.githubusercontent.com/kubernetes/kompose/master/examples/docker-compose.yaml +``` + +__Convert your Docker Compose file to OpenShift:__ + +Run `kompose convert --provider=openshift` in the same directory as your `docker-compose.yaml` file. + +```sh +$ kompose convert --provider=openshift +INFO OpenShift file "frontend-service.yaml" created +INFO OpenShift file "redis-master-service.yaml" created +INFO OpenShift file "redis-slave-service.yaml" created +INFO OpenShift file "frontend-deploymentconfig.yaml" created +INFO OpenShift file "frontend-imagestream.yaml" created +INFO OpenShift file "redis-master-deploymentconfig.yaml" created +INFO OpenShift file "redis-master-imagestream.yaml" created +INFO OpenShift file "redis-slave-deploymentconfig.yaml" created +INFO OpenShift file "redis-slave-imagestream.yaml" created +``` + +Alternatively, you can convert and deploy directly to OpenShift with `kompose up --provider=openshift`. + +```sh +$ kompose up --provider=openshift +INFO We are going to create OpenShift DeploymentConfigs, Services and PersistentVolumeClaims for your Dockerized application. +If you need different kind of resources, use the 'kompose convert' and 'oc create -f' commands instead. + +INFO Deploying application in "myproject" namespace +INFO Successfully created Service: frontend +INFO Successfully created Service: redis-master +INFO Successfully created Service: redis-slave +INFO Successfully created DeploymentConfig: frontend +INFO Successfully created ImageStream: frontend +INFO Successfully created DeploymentConfig: redis-master +INFO Successfully created ImageStream: redis-master +INFO Successfully created DeploymentConfig: redis-slave +INFO Successfully created ImageStream: redis-slave + +Your application has been deployed to OpenShift. You can run 'oc get dc,svc,is,pvc' for details. +``` + +__Access the newly deployed service:__ + +After deployment, you must create an OpenShift route in order to access the service. + +If you're using `minishift`, you'll use a combination of `oc` and `minishift` commands to access the service. + +Create a route for the `frontend` service using `oc`: + +```sh +$ oc expose service/frontend +route "frontend" exposed +``` + +Access the `frontend` service with `minishift`: + +```sh +$ minishift openshift service frontend --namespace=myproject +Opening the service myproject/frontend in the default browser... +``` + +You can also access the GUI interface of OpenShift for an overview of the deployed containers: + +```sh +$ minishift console +Opening the OpenShift Web console in the default browser... +``` + +## RHEL and Kompose + +In this guide, we'll deploy a sample `docker-compose.yaml` file using both RHEL (Red Hat Enterprise Linux) and OpenShift. + +Requirements: + - Red Hat Enterprise Linux 7.4 + - [Red Hat Development Suite](https://developers.redhat.com/products/devsuite/overview/) + - Which includes: + - [minishift](https://github.com/minishift/minishift) + - [kompose](https://github.com/kubernetes/kompose) + +__Note:__ A KVM hypervisor must be setup in order to correctly use `minishift` on RHEL. You can set it up via the [CDK Documentation](https://access.redhat.com/documentation/en-us/red_hat_container_development_kit/3.1/html-single/getting_started_guide/index#setup-virtualization) under "Set up your virtualization environment". + +__Install Red Hat Development Suite:__ + +Before we are able to use both `minishift` and `kompose`, DevSuite must be installed. A more concise [installation document is available](https://developers.redhat.com/products/devsuite/hello-world/#fndtn-rhel). + +Change to root. + +```sh +$ su - +``` + +Enable the Red Hat Developer Tools software repository. + +```sh +$ subscription-manager repos --enable rhel-7-server-devtools-rpms +$ subscription-manager repos --enable rhel-server-rhscl-7-rpms +``` + +Add the Red Hat Developer Tools key to your system. + +```sh +$ cd /etc/pki/rpm-gpg +$ wget -O RPM-GPG-KEY-redhat-devel https://www.redhat.com/security/data/a5787476.txt +$ rpm --import RPM-GPG-KEY-redhat-devel +``` + +Install Red Hat Development Suite and Kompose. + +```sh +$ yum install rh-devsuite kompose -y +``` + +__Start `minishift`:__ + +Before we begin, we must do a few preliminary steps setting up `minishift`. + +```sh +$ su - +$ ln -s /var/lib/cdk-minishift-3.0.0/minishift /usr/bin/minishift +$ minishift setup-cdk --force --default-vm-driver="kvm" +$ ln -s /home/$(whoami)/.minishift/cache/oc/v3.5.5.8/oc /usr/bin/oc +``` + +Now we may start `minishift`. + +```sh +$ minishift start +Starting local OpenShift cluster using 'kvm' hypervisor... +-- Checking OpenShift client ... OK +-- Checking Docker client ... OK +-- Checking Docker version ... OK +-- Checking for existing OpenShift container ... OK +... +``` + +__Download an [example Docker Compose file](https://raw.githubusercontent.com/kubernetes/kompose/master/examples/docker-compose.yaml), or use your own:__ + +```sh +wget https://raw.githubusercontent.com/kubernetes/kompose/master/examples/docker-compose.yaml +``` + +__Convert your Docker Compose file to OpenShift:__ + +Run `kompose convert --provider=openshift` in the same directory as your `docker-compose.yaml` file. + +```sh +$ kompose convert --provider=openshift +INFO OpenShift file "frontend-service.yaml" created +INFO OpenShift file "redis-master-service.yaml" created +INFO OpenShift file "redis-slave-service.yaml" created +INFO OpenShift file "frontend-deploymentconfig.yaml" created +INFO OpenShift file "frontend-imagestream.yaml" created +INFO OpenShift file "redis-master-deploymentconfig.yaml" created +INFO OpenShift file "redis-master-imagestream.yaml" created +INFO OpenShift file "redis-slave-deploymentconfig.yaml" created +INFO OpenShift file "redis-slave-imagestream.yaml" created +``` + +Alternatively, you can convert and deploy directly to OpenShift with `kompose up --provider=openshift`. + +```sh +$ kompose up --provider=openshift +INFO We are going to create OpenShift DeploymentConfigs, Services and PersistentVolumeClaims for your Dockerized application. +If you need different kind of resources, use the 'kompose convert' and 'oc create -f' commands instead. + +INFO Deploying application in "myproject" namespace +INFO Successfully created Service: frontend +INFO Successfully created Service: redis-master +INFO Successfully created Service: redis-slave +INFO Successfully created DeploymentConfig: frontend +INFO Successfully created ImageStream: frontend +INFO Successfully created DeploymentConfig: redis-master +INFO Successfully created ImageStream: redis-master +INFO Successfully created DeploymentConfig: redis-slave +INFO Successfully created ImageStream: redis-slave + +Your application has been deployed to OpenShift. You can run 'oc get dc,svc,is,pvc' for details. +``` + +__Access the newly deployed service:__ + +After deployment, you must create an OpenShift route in order to access the service. + +If you're using `minishift`, you'll use a combination of `oc` and `minishift` commands to access the service. + +Create a route for the `frontend` service using `oc`: + +```sh +$ oc expose service/frontend +route "frontend" exposed +``` + +Access the `frontend` service with `minishift`: + +```sh +$ minishift openshift service frontend --namespace=myproject +Opening the service myproject/frontend in the default browser... +``` + +You can also access the GUI interface of OpenShift for an overview of the deployed containers: + +```sh +$ minishift console +Opening the OpenShift Web console in the default browser... +``` diff --git a/docs/introduction.md b/docs/introduction.md new file mode 100644 index 00000000..b5eff4a9 --- /dev/null +++ b/docs/introduction.md @@ -0,0 +1,59 @@ +# Kubernetes + Compose = Kompose +## A conversion tool to go from Docker Compose to Kubernetes + +### What's Kompose? + +Kompose is a conversion tool for Docker Compose to container orchestrators such as Kubernetes (or OpenShift). + +Why do developers love it? + + - Simplify your development process with Docker Compose and then deploy your containers to a production cluster + - Convert your `docker-compose.yaml` with one simple command `kompose convert` + - Immediately bring up your cluster with `kompose up` + - Bring it back down with `kompose down` + +### It's as simple as 1-2-3 + +1. [Use an example docker-compose.yaml file](https://raw.githubusercontent.com/kubernetes/kompose/master/examples/docker-compose-v3.yaml) or your own +2. Run `kompose up` +3. Check your Kubernetes cluster for your newly deployed containers! + +```sh +$ wget https://raw.githubusercontent.com/kubernetes/kompose/master/examples/docker-compose-v3.yaml + +$ kompose up +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 Successfully created Service: redis +INFO Successfully created Service: web +INFO Successfully created Deployment: redis +INFO Successfully created Deployment: web + +Your application has been deployed to Kubernetes. You can run 'kubectl get deployment,svc,pods,pvc' for details. + +$ kubectl get po +NAME READY STATUS RESTARTS AGE +frontend-591253677-5t038 1/1 Running 0 10s +redis-master-2410703502-9hshf 1/1 Running 0 10s +redis-slave-4049176185-hr1lr 1/1 Running 0 10s +``` + +A more detailed guide is available in our [getting started guide](/docs/getting-started.md). + +### Install Kompose on Linux, macOS or Windows + +Grab the Kompose binary! + +```sh +# Linux +curl -L https://github.com/kubernetes/kompose/releases/download/v1.2.0/kompose-linux-amd64 -o kompose + +# macOS +curl -L https://github.com/kubernetes/kompose/releases/download/v1.2.0/kompose-darwin-amd64 -o kompose + +chmod +x kompose +sudo mv ./kompose /usr/local/bin/kompose +``` + +_Windows:_ Download from [GitHub](https://github.com/kubernetes/kompose/releases/download/v1.2.0/kompose-windows-amd64.exe) and add the binary to your PATH. diff --git a/docs/quickstart.md b/docs/quickstart.md deleted file mode 100644 index 281e745a..00000000 --- a/docs/quickstart.md +++ /dev/null @@ -1,110 +0,0 @@ -# Kubernetes + Compose = Kompose - -What's Kompose? It's a conversion tool for all things compose (namely Docker Compose) to container orchestrators (Kubernetes or OpenShift). - -In three simple steps, we'll take you from Docker Compose to Kubernetes. - -__1. Take a sample docker-compose.yaml file__ - -```yaml -version: "2" - -services: - - redis-master: - image: gcr.io/google_containers/redis:e2e - ports: - - "6379" - - redis-slave: - image: gcr.io/google_samples/gb-redisslave:v1 - ports: - - "6379" - environment: - - GET_HOSTS_FROM=dns - - frontend: - image: gcr.io/google-samples/gb-frontend:v4 - ports: - - "80:80" - environment: - - GET_HOSTS_FROM=dns - labels: - kompose.service.type: LoadBalancer -``` - -__2. Run `kompose up` in the same directory__ - -```bash -$ kompose up -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 Successfully created Service: redis -INFO Successfully created Service: web -INFO Successfully created Deployment: redis -INFO Successfully created Deployment: web - -Your application has been deployed to Kubernetes. You can run 'kubectl get deployment,svc,pods,pvc' for details. -``` - -__Alternatively, you can run `kompose convert` and deploy with `kubectl`__ - -__2.1. Run `kompose convert` in the same directory__ - -```bash -$ kompose convert -INFO Kubernetes file "frontend-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 "redis-master-deployment.yaml" created -INFO Kubernetes file "redis-slave-deployment.yaml" created -``` - -__2.2. And start it on Kubernetes!__ - -```bash -$ kubectl create -f frontend-service.yaml,redis-master-service.yaml,redis-slave-service.yaml,frontend-deployment.yaml,redis-master-deployment.yaml,redis-slave-deployment.yaml -service "frontend" created -service "redis-master" created -service "redis-slave" created -deployment "frontend" created -deployment "redis-master" created -deployment "redis-slave" created -``` - -__3. View the newly deployed service__ - -Now that your service has been deployed, let's access it. - -If you're already using `minikube` for your development process: - -```bash -$ minikube service frontend -``` - -Otherwise, let's look up what IP your service is using! - -```sh -$ kubectl describe svc frontend -Name: frontend -Namespace: default -Labels: service=frontend -Selector: service=frontend -Type: LoadBalancer -IP: 10.0.0.183 -LoadBalancer Ingress: 123.45.67.89 -Port: 80 80/TCP -NodePort: 80 31144/TCP -Endpoints: 172.17.0.4:80 -Session Affinity: None -No events. - -``` - -If you're using a cloud provider, your IP will be listed next to `LoadBalancer Ingress`. - -```sh -$ curl http://123.45.67.89 -``` diff --git a/docs/user-guide.md b/docs/user-guide.md index 820f47ab..17ccd12c 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -1,9 +1,10 @@ # User Guide -- CLI - - [`kompose convert`](#kompose-convert) - - [`kompose up`](#kompose-up) - - [`kompose down`](#kompose-down) +- Command Line + - [Kompose Convert](#kompose-convert) + - [Kompose Up](#kompose-up) + - [Kompose Down](#kompose-down) + - Documentation - [Build and Push Docker Images](#build-and-push-docker-images) - [Alternative Conversions](#alternative-conversions) @@ -15,7 +16,7 @@ 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 Convert Kompose supports conversion of V1, V2, and V3 Docker Compose files into Kubernetes and OpenShift objects. @@ -100,7 +101,7 @@ 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`. @@ -177,7 +178,7 @@ 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. diff --git a/script/sync-docs.sh b/script/sync-docs.sh index 41f76319..e5449f4b 100755 --- a/script/sync-docs.sh +++ b/script/sync-docs.sh @@ -33,8 +33,8 @@ git checkout master docs # Remove README.md from docs folder as it isn't relevant rm docs/README.md -# Use quickstart.md instead as the main index page -mv docs/quickstart.md index.md +# Use introduction.md instead as the main index page +mv docs/introduction.md index.md # Check that index.md has the appropriate Jekyll format index="index.md"