Improve readme and add inventory docs

Readme covers main deployment styles
Added example inventory
Added document on how to generate inventory

Change-Id: I8077cef6452341c76b61f91fe6b19ec4deec5784

README.rst

@@ -1,4 +1,39 @@
-Express Fuel CCP setup using Kargo
-----------------------------------
+Express Fuel CCP Kubernetes deployment using Kargo
+--------------------------------------------------
 
-TBD
+Deploy Kubernetes on pre-provisioned virtual or bare metal hosts
+
+This project leverages [Kargo](https://github.com/kubespray/kargo) to deploy
+Kubernetes with Calico networking plugin.
+
+There are four ways you can use to deploy:
+
+* Preprovisioned list of hosts
+* Precreated Ansible inventory
+* Vagrant
+* [fuel-devops](https://github.com/openstack/fuel-devops)
+
+Preprovisioned list of hosts
+----------------------------
+
+See [Quickstart guide](doc/source/quickstart.rst)
+
+Precreated Ansible inventory
+----------------------------
+
+See [Generating Ansible Inventory](doc/source/generate-inventory.rst)
+
+Vagrant
+-------
+
+Vagrant support is limited at this time. Try it and report bugs if you see any!
+
+Using VirtualBox
+::
+vagrant up --provider virtualbox
+
+Using Libvirt
+::
+sudo sh -c 'echo 0 > /proc/sys/net/bridge/bridge-nf-call-iptables'
+vagrant plugin --install vagrant-libvirt
+vagrant up --provider libvirt

config.yaml.sample

@@ -1,16 +0,0 @@
----
-kube_master:
-  username: vagrant
-  password: vagrant
-  ssh_key: null
-  ip: 10.0.0.3
-global_config:
-  cluster_dns: 10.254.0.10
-  cluster_domain: cluster.local
-kube_slaves:
-  default:
-    username: vagrant
-    password: vagrant
-    ssh_key: null
-  slaves:
-    - ip: 10.0.0.4

doc/source/generate_inventory.rst

@@ -0,0 +1,68 @@
+Generating Ansible Inventory
+============================
+
+Ansible makes use of an inventory file in order to list hosts, host groups, and
+specify individual host variables. This file can be in any of three formats:
+inifile, JSON, or YAML. Fuel CCP Installer only makes use of inifile format.
+
+For many users, it is possible to generate Ansible inventory with the help of
+your bare metal provisioner, such as `Cobbler <http://cobbler.github.io>`_ or
+`Foreman <http://theforman.org>`_. For further reading, refer to the
+documentation on `Dynamic Inventory <http://docs.ansible.com/ansible/intro_dynamic_inventory.html>`_.
+
+Fuel CCP Installer takes a different approach, due its git-based workflow. You
+can still use any tool you wish to generate Ansible inventory, but you need to
+save this inventory file to the path `$ADMIN_WORKSPACE/inventory`.
+
+Below you can find a few examples on how generate Ansible inventory that can be
+used for deployment.
+
+Using Fuel CCP's simple inventory generator
+-------------------------------------------
+If you run kargo_deploy.sh with a predefined list of nodes, it will generate
+Ansible inventory for you automatically. Below is an example:
+
+::
+$ SLAVE_IPS="10.90.0.2 10.90.0.3 10.90.0.4" utils/jenkins/kargo_deploy.sh
+
+This will generate the same inventory as the example
+`inventory <https://github.com/openstack/fuel-ccp-installer/blob/master/inventory.cfg.sample>`_
+file. Role distribution is as follows:
+
+* The first 2 hosts have Kubernetes Master role
+* The first 3 hosts have ETCD role
+* All hosts have Kubernetes Node role
+
+Using Kargo-cli
+---------------
+
+You can use `Kargo-cli <https://github.com/kubespray/kargo-cli>` tool to
+generate Ansible inventory with some more complicated role distribution. Below
+is an example you can use (indented for visual effect):
+
+::
+$ sudo apt-get install python-dev python-pip gcc libssl-dev libffi-dev
+$ pip install kargo
+$ kargo --noclone -i inventory.cfg prepare \
+  --nodes \
+    node1[ansible_ssh_host=10.90.0.2,ip=10.90.0.2] \
+    node2[ansible_ssh_host=10.90.0.3,ip=10.90.0.3] \
+    node3[ansible_ssh_host=10.90.0.4,ip=10.90.0.4] \
+  --etcds \
+    node4[ansible_ssh_host=10.90.0.5,ip=10.90.0.5] \
+    node5[ansible_ssh_host=10.90.0.6,ip=10.90.0.6] \
+    node6[ansible_ssh_host=10.90.0.7,ip=10.90.0.7] \
+  --masters \
+    node7[ansible_ssh_host=10.90.0.5,ip=10.90.0.8] \
+    node8[ansible_ssh_host=10.90.0.6,ip=10.90.0.9]
+
+This allows more granular control over role distribution, but kargo-cli has
+several dependencies because it several other functions.
+
+Manual inventory creation
+-------------------------
+
+You can simply Generate your inventory by hand by using the example
+`inventory <https://github.com/openstack/fuel-ccp-installer/blob/master/inventory.cfg.sample>`_
+file and save it as inventory.cfg. Note that all groups are required and you
+should only define host variables inside the [all] section.

inventory.cfg.sample

@@ -0,0 +1,23 @@
+[kube-master]
+node1
+node2
+
+[all]
+node1 	 ansible_ssh_host=10.90.0.2 ip=10.90.0.2
+node2 	 ansible_ssh_host=10.90.0.3 ip=10.90.0.3
+node3 	 ansible_ssh_host=10.90.0.4 ip=10.90.0.4
+
+[k8s-cluster:children]
+kube-node
+kube-master
+
+[kube-node]
+node1
+node2
+node3
+
+[etcd]
+node1
+node2
+node3
+