deep-stack/kompose
7
0
Fork 0
forked from LaconicNetwork/kompose
Code Pull Requests Activity

Merge pull request #834 from cdrage/docs-update

Browse Source 
Add Getting Started guide, adds Minishift tutorial
This commit is contained in:
Charlie Drage 2017-10-06 10:07:58 -04:00 committed by GitHub
commit 07cfc1fe28
6 changed files with 419 additions and 120 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/README.md
View File

@ -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)

347
docs/getting-started.md Normal file
View File

@ -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...
```

59
docs/introduction.md Normal file
View File

@ -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.

110
docs/quickstart.md
View File

@ -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
```

15
docs/user-guide.md
View File

@ -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.

4
script/sync-docs.sh
View File

@ -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"