adding files

1 files changed, 124 insertions, 1 deletions

diff --git a/README.md b/README.md
index 118f4a5..365eabd 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,124 @@
-# openbook-v3-installer
+# Overview
+
+Welcome to the Talligent ansible playbooks. There is one for spinning
+up the bare VMs, one for installing Openbook and all its dependencies
+on the VMs, and one for upgrading Openbook when we are given a new WAR
+file.
+
+    Spin up new VMs: spin_up_bare_vm.yaml (to be replaced with heat)
+    Install Openbook on the VMs: install_openbook.yaml
+    Update the Openbook application: update_openbook.yaml
+
+# Prerequisites
+
+There must first be a project named "talligent" in the environment,
+and it must have a pre-existing DNS domain created via Horizon. The
+showback user must have the following roles on the talligent project:
+
+ResellerAdmin
+lbaas_project_admin
+admin
+designate_project_admin
+
+Puppet should take care of assigning these roles.
+
+# spin_up_bare_vm.yaml playbook:
+
+This playbook spins up a new VM, sets up networking, security groups
+and DNS. It will be reimplemented as a heat template in the near
+future. The reason it's a standalone playbook now is to make it easier
+to replace.
+
+Run this playbook first. If you want two Openbook nodes, run it twice
+in a row. Use 'openstack server list' or horizon to ensure that you
+have the VMs you desire.
+
+This playbook relies on an environment. Source the appropriate
+openrc-* file in the conf/ directory.
+
+In BFD02 you only need to source one environment and spin up two
+VMs. In staging and production you will have to spin up two VMs in a
+region, source the other region's openrc file, and spin up two more
+VMs.
+
+It is important to spin up all the VMs before moving on to the
+install_openbook.yaml playbook.
+
+It is also vitally important that your VMs have the IP addresses that
+are listed in conf/env.yaml.
+
+The first time you run this playbook it will create a new VM called
+<siteiter>-openbook-001. Subsequent runs will create VMs ending in
+002, 003, etc. Normally you will not go past two VMs. Production and
+staging have special FIPs that have access to the keystone admin
+URL. As mentioned above, your VMs must get the FIPs that are listed in
+conf/env.yaml.
+
+Sample invocation:
+
+    ansible-playbook spin_up_bare_vm.yaml
+
+See below for a full usage scenario.
+
+# install_openbook.yaml playbook:
+
+This playbook installs Openbook and all its dependencies on the
+VMs. It acts on all the VMs in the environment. You can look at
+conf/env.yaml to see which VMs are expected to pre-exist.
+
+You do not need to source an openrc file to run this playbook. All the
+data is in conf/env.yaml. It doesn't matter if your shell has an
+openrc file already sourced. This playbook ignores the environment
+entirely.
+
+Invoke the playbook as follows:
+
+    ansible-playbook -i dynamic_hosts_[env].py install_openbook.yaml
+
+There is a script called dynamic_hosts.py that reads conf/env.yaml and
+transforms the data into JSON. You have to tell it which environment
+you want. The way you do that is to use the appropriate symlink that
+contains the environment name. There are three possible invocations:
+
+    ansible-playbook -i dynamic_hosts_lab.py install_openbook.yaml
+    ansible-playbook -i dynamic_hosts_staging.py install_openbook.yaml
+    ansible-playbook -i dynamic_hosts_prod.py install_openbook.yaml
+
+You only need to run this playbook once regardless of how many VMs
+there are. It will hit every VM in the inventory that is generated by
+the python script.
+
+In staging and production the resulting configuration will include a
+cross-region galera cluster.
+
+# update_openbook.yaml
+
+This playbook will only update the Openbook application with a new WAR
+file that is on blobmaster. (See
+bfd01-blobmaster-001:/bfd01/swift/Openbook.war) This is what you will
+always use once a cluster is up.
+
+You do not need to source an openrc file to run this playbook. All the
+data is in conf/env.yaml.
+
+You must feed it the dynamic inventory:
+
+    ansible-playbook -i dynamic_hosts_[env].py update_openbook.yaml
+
+# Usage
+
+To build a new cluster: shell onto the build node in the environment
+in which you want to spin up an Openbook cluster.
+
+    cd /etc/ansible/oneoff/talligent/
+    . conf/openrc-[your-desired-profile]
+    ansible-playbook spin_ip_bare_vm.yaml
+    ansible-playbook spin_ip_bare_vm.yaml
+    . conf/openrc-[your-other-desired-profile]
+    ansible-playbook spin_ip_bare_vm.yaml
+    ansible-playbook spin_ip_bare_vm.yaml
+    ansible-playbook -i dynamic_hosts_[env].py install_openbook.yaml
+
+To update an existing cluster with a new WAR file:
+
+    ansible-playbook -i dynamic_hosts_[env].py update_openbook.yaml