Add general instructions for deploying infrastructure to OpenStack

Also, add some placeholders to README so we can make the instructions
listed in the README easier to cut-n-paste, even when deploying to
somewhere other than DataCentred.

Change-Id: I32ca1073b7a956a7b8a21ad67682c6292c9d91af

1 files changed, 56 insertions, 3 deletions

diff --git a/README.mdwn b/README.mdwn
index 6b022167..3b2501ff 100644
--- a/README.mdwn
+++ b/README.mdwn
@@ -50,6 +50,59 @@ To run an ad-hoc command (upgrading, for example):
 [Ansible]: http://www.ansible.com
 
 
+Deployment to OpenStack
+-----------------------
+
+The intention is that all of the systems defined here are deployed to an
+OpenStack cloud. The instructions here harcode some details about the specific
+tenancy at [DataCentred](http://www.datacentred.io) that the Baserock project
+uses. It should be easy to adapt them for other OpenStack hosts, though.
+
+### Credentials
+
+The instructions below assume you have the following environment variables set
+according to the OpenStack host you are deploying to:
+
+ - `OS_AUTH_URL`
+ - `OS_TENANT_NAME`
+ - `OS_USERNAME`
+ - `OS_PASSWORD`
+
+When using `morph deploy` to deploy to OpenStack, you will need to set these
+variables, because currently Morph does not honour the standard ones. See:
+<https://storyboard.baserock.org/#!/story/35>.
+
+ - `OPENSTACK_USER=$OS_USERNAME`
+ - `OPENSTACK_PASSWORD=$OS_PASSWORD`
+ - `OPENSTACK_TENANT=$OS_TENANT_NAME`
+
+The `location` field in the deployment .morph file will also need to point to
+the correct `$OS_AUTH_URL`.
+
+### Firewall / Security Groups
+
+The instructions assume the presence of a set of security groups. You can
+create these by running the following Ansible playbook. You'll need the
+OpenStack Ansible modules cloned from
+`https://github.com/openstack-ansible/openstack-ansible-modules/`.
+
+    ANSIBLE_LIBRARY=../openstack-ansible-modules ansible-playbook -i hosts \
+        firewall.yaml
+
+### Placeholders
+
+The commands below use a couple of placeholders like $network_id, you can set
+them in your environment to allow you to copy and paste the commands below
+as-is.
+
+ - `export fedora_image_id=...` (find this with `glance image-list`)
+ - `export network_id=...` (find this with `neutron net-list`)
+ - `export keyname=...` (find this with `nova keypair-list`)
+
+The `$fedora_image_id` should reference a Fedora Cloud image. You can import
+these from <http://www.fedoraproject.org/>. At time of writing, these
+instructions were tested with Fedora Cloud 21 for x86_64.
+
 Backups
 -------
 
@@ -208,7 +261,7 @@ https://docs.djangoproject.com/en/1.7/howto/deployment/checklist/
         --key-name $keyname \
         --flavor dc1.1x1 \
         --image 'baserock_openid_provider' \
-        --nic 'net-id=d079fa3e-2558-4bcb-ad5a-279040c202b5',v4-fixed-ip=192.168.222.67 \
+        --nic "net-id=$network_id',v4-fixed-ip=192.168.222.67" \
         --security-groups default,web-server
         --user-data ./baserock-ops-team.cloud-config
 
@@ -243,7 +296,7 @@ or 'build' system.
         --key-name $keyname \
         --flavor 'dc1.2x4.40' \
         --image baserock_gerrit \
-        --nic net-id=d079fa3e-2558-4bcb-ad5a-279040c202b5,v4-fixed-ip=192.168.222.69 \
+        --nic "net-id=$network_id,v4-fixed-ip=192.168.222.69" \
         --security-groups default,gerrit,git-server,web-server
         --user-data baserock-ops-team.cloud-config
 
@@ -392,7 +445,7 @@ To deploy the production version:
     nova boot openid_provider
         --flavor dc1.1x1 --image 'baserock_storyboard' \
         --key-name=$keyname storyboard.baserock.org \
-        --nic='net-id=d079fa3e-2558-4bcb-ad5a-279040c202b5'
+        --nic="net-id=$network_id"
         --security-groups default,web-server
         --user-data baserock-ops-team.cloud-config