From 4724eb11e2f2334f268971ef4ebf4a9c122cdacc Mon Sep 17 00:00:00 2001
From: Steven Dake <sdake@redhat.com>
Date: Tue, 21 Oct 2014 06:50:58 -0700
Subject: [PATCH] Tidy up README.md
The readme was woefully old. Make it more modern to match the current
state of the repository and development.
Change-Id: I9be10ca8565835c784afea63ee70978d10313e4a
---
README.md | 201 ++++++++++++++++++++++++++++++++++--------------------
1 file changed, 126 insertions(+), 75 deletions(-)
diff --git a/README.md b/README.md
index 93f37c3b20..5d3767fc85 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,7 @@ Getting Started
===============
Kubernetes deployment on bare metal is a complex topic which is beyond the
-scope of this project at this time. The developers still require a test
+scope of this project at this time. The developers require a development test
environment. As a result, one of the developers has created a Heat based
deployment tool that can be
found [here](https://github.com/larsks/heat-kubernetes).
@@ -21,73 +21,142 @@ found [here](https://github.com/larsks/heat-kubernetes).
Build Docker Images
-------------------
-Within the docker directory is a tool called build. This tool will build
-all of the docker images that have been implemented. Each OpenStack service is
-implemented as a separate container that can later be registered with
-Kubernetes. These containers are published to the the public docker registry and
-are referenced in the kubernetes configuration files in this repo.
+Images are built by the Kolla project maintainers. It is possible to build
+unique images with specific changes, but these would end up in a personal
+namespace. Read the docs directory image workflow documentation for more
+details.
+
+The Kolla developers build images in the kollaglue namespace for the following
+services:
+Glance
+Heat
+Keystone
+Mariadb
+Nova
+Rabbitmq
```
-[sdake@bigiron docker]$ sudo ./build
+$ sudo docker search kollaglue
```
-
-A 20-30 minute build process will begin where containers will be built for
-each OpenStack service. Once finished the docker images can be examined with
-the docker CLI.
-
-```
-[sdake@bigiron docker]$ sudo docker images
-```
-
-A list of the built docker images will be shown.
-
-Note at this time the images do not yet work correctly or operate on their
-defined environment variables. They are essentially placeholders.
-
+A list of the upstream built docker images will be shown.
Use Kubernetes to Deploy OpenStack
----------------------------------
-Keystone and MariaDB are the only pods that are implimented. They operate
-just enough to verify that services are running and may have bugs in their configurations.
+At this point, we believe the key features for a minimum viable feature set
+are implemented. This includes the capability to launch virtual machines in
+Nova. One key fact is that networking may not entirely work properly yet
+until Neutron is finished, so the virtual machines may not actually behave
+as expected for an end user deployment.
-To get Keystone running start by downloading the pod and service json files for MariaDB
-to a running kubernetes cluster.
-```
-curl https://raw.githubusercontent.com/stackforge/kolla/master/k8s/service/mariadb-service.json > mariadb-service.json
-curl https://raw.githubusercontent.com/stackforge/kolla/master/k8s/pod/mariadb-pod.json > mariadb-pod.json
-```
+Two options exist for those without an existing Kubernetes environment:
-Next launch the MariaDB pod and service files. The services are started first incase the pods reference
-their addresses. You'll see the same thing in keystone when it's launched.
-```
-$ kubecfg -c mariadb-service.json create services
-ID Labels Selector Port
----------- ---------- ---------- ----------
-mariadb name=mariadb 3306
+The upstream Kubernetes community provides instructions for running Kubernetes
+using Vagrant, available from:
+https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/getting-started-guides/vagrant.md
+
+The Kolla developers develop Kolla in OpenStack, using Heat to provision the
+necessary servers and other resources. If you are familiar with Heat and
+have a correctly configured environment available, this allows deployment
+of a working Kubernetes cluster automatically. The Heat templates are
+available from https://github.com/larsks/heat-kubernetes/. The templates
+require at least Heat 2014.1.3 (earlier versions have a bug that will prevent
+the templates from working).
+
+Here are some simple steps to get things rolling using the Heat templates:
+
+1. git clone https://github.com/larsks/heat-kubernetes/; cd heat-kubernetes
+
+2. Create an appropriate image by running the get_image.sh script in this repository. This will generate an image called "fedora-20-k8s.qcow2". Upload this image to Glance. You can also obtain an appropriate image from
+https://fedorapeople.org/groups/heat/kolla/fedora-20-k8s.qcow2
+
+3. Create a file "local.yaml" with settings appropriate to your OpenStack environment. It should look something like:
+
+parameters:
+ server_image: fedora-20-k8s
+ ssh_key_name: sdake
+
+
+ dns_nameserver: 8.8.8.8
+ external_network_id: 6e7e7701-46a0-49c0-9f06-ac5abc79d6ae
+ number_of_minions: 1
+ server_flavor: m1.large
+
+You *must* provide settings for external_network_id and ssh_key_name; these are
+local to your environment. You will probably also need to provide a value for
+server_image, which should be the name (or UUID) of a Fedora 20 cloud image or
+derivative.
+
+4. heat stack-create -f kubecluster.yaml -e local.yaml my-kube-cluster
+5. Determine the ip addresses of your cluster hosts by running:
+
+ heat output-show my-kube-cluster kube_minions_external
+
+6. ssh fedora@${minion-ip}
+7. minion$ git clone http://github.com/stackforge/kolla
+8. minion$ cd kolla
+9. minion$ ./tools/start
+
+Debugging
+==========
+A few commands for debugging the system.
-$ kubecfg -c mariadb-pod.json create pods
-ID Image(s) Host Labels Status
----------- ---------- ---------- ---------- ----------
-mariadb kollaglue/fedora-rdo-mariadb / name=mariadb Waiting
```
-To verify their creation and see their status use the list command. You are ready to move on when the
-pod's status reaches **Running**.
+$ sudo docker images
+```
+Lists all images that have been pulled from the upstream kollaglue repository
+thus far. This can be run on the minion during the ./start operation to check
+on the download progress.
+
+
+```
+$ sudo docker ps -a
+```
+This will show all processes that docker has started. Removing the -a will
+show only active processes. This can be run on the minion during the ./start
+operation to check that the containers are orchestrated.
+
+
+```
+$ sudo docker logs <containerid>
+```
+This shows the logging output of each service in a container. The containerid
+can be obtained via the docker ps operation. This can be run on the minion
+during the ./start operation to debug the container.
+
```
$ kubecfg list pods
-ID Image(s) Host Labels Status
----------- ---------- ---------- ---------- ----------
-mariadb kollaglue/fedora-rdo-mariadb 10.0.0.3/ name=mariadb Running
```
-If MariaDB doesn't move to running within a few minutes use journalctl on the master and the nodes to
-troubleshoot. The first command is for the master and the second is for the nodes.
+This lists all pods of which Kubernetes is aware. This can be run on the
+master or minion.
+
+```
+$ sudo systemctl restart kube-apiserver
+$ sudo systemctl restart kube-scheduler
+```
+This command is needed on the master after heat finishes the creation of the
+Kubernetes system (ie: my-kube-cluster is in CREATE_COMPLETE state). This is
+just a workaround for a bug in kubernetes that should be fixed soon.
+
+
```
$ journalctl -f -l -xn -u kube-apiserver -u etcd -u kube-scheduler
+```
+This shows log output on the server for the various daemons and can be filed
+in bug reports in the upstream launchpad tracker.
+
+```
$ journalctl -f -l -xn -u kubelet.service -u kube-proxy -u docker
```
-Once the pod's status reaches running you should verify that you can connect to the database through all the
-kube-proxies. You can use telnet to do this. Telnet to 3306 on each node and make sure mysql responds.
+This shows log output on the minion for the various daemons and can be filed
+in bug reports in the upstream launchpad tracker.
+
```
+$ telnet minion_ip 3306
+```
+This shows that the Mariadb service is running on the minions. Output should
+appear as follows
+
$ telnet 10.0.0.4 3306
Trying 10.0.0.4...
Connected to 10.0.0.4.
@@ -95,39 +164,21 @@ Escape character is '^]'.
5.5.39-MariaDB-wsrep
-$ telnet 10.0.0.3 3306
-Trying 10.0.0.3...
-Connected to 10.0.0.3.
-Escape character is '^]'.
+If the connection closes before mysql responds then the proxy is not properly
+connecting to the database. This can be seen by using jounalctl and watching
+for a connection error on the node that you can't connect to mysql through.
-5.5.39-MariaDB-wsrep
-```
-If the connection closes before mysql responds then the proxy is not properly connecting to the database.
-This can be seen by using jounalctl and watching for a connection error on the node that you can't connect
-to mysql through.
```
$ journalctl -f -l -xn -u kube-proxy
```
-If you can conect though one and not the other there's probably a problem with the overlay network. Double
-check that you're tunning kernel 3.16+ because vxlan support is required. If you kernel version is good
-try restarting openvswitch on both nodes. This has usually fixed the connection issues for me.
-
-If you're able to connect to mysql though both proxies then you're ready to launch keystone. Download and
-use the pod and service files to launch the pods and services for keystone.
-```
-$ curl https://raw.githubusercontent.com/stackforge/kolla/master/k8s/keystone/keystone-admin-service.json > keystone-admin-service.json
-$ curl https://raw.githubusercontent.com/stackforge/kolla/master/k8s/keystone/keystone-public-service.json > keystone-public-service.json
-$ curl https://raw.githubusercontent.com/stackforge/kolla/master/k8s/pod/keystone-pod.json > keystone-pod.json
-$ kubecfg -c keystone-keystone-public.json create services
-$ kubecfg -c keystone-keystone-admin.json create services
-$ kubecfg -c keystone-pod.json create pods
-```
-The keystone pod should become status running, if it doesn't you can troubleshoot it the same way that the
-database was. Once keystone is running you should be able to use the keystone client to do a token-get
-against one of the proxy's ip addresses.
+If you can conect though one and not the other there's probably a problem with
+the overlay network. Double check that you're tunning kernel 3.16+ because
+vxlan support is required. If you kernel version is good try restarting
+openvswitch on both nodes. This has usually fixed the connection issues.
Directories
===========
* docker - contains artifacts for use with docker build to build appropriate images
* k8s - contains service and pod configuration information for Kubernetes
+* tools - contains different tools for interacting with Kolla