[DOCS] Cleanup the role docs for consistency and clarity

Utilizing RST includes to reduce duplication of documentation
effort. All contents of the Ansible defaults/main.yml are
now included in the documentation directly.

Change-Id: Ib3d0caa4a23550f201887b075bb8f0de5d9f6c26

README.rst

@@ -1,13 +1,45 @@
-OpenStack keystone
-##################
-:tags: openstack, keystone, cloud, ansible
-:category: \*nix
+OpenStack-Ansible Keystone
+##########################
 
-Role to install keystone. This will install keystone using apache.
+Ansible role that installs and configures OpenStack Keystone. Keystone is
+installed behind the Apache webserver listening on port 5000 and port 35357 by
+default.
 
-This role will install the following:
-    * keystone
-    * apache2
+Default Variables
+=================
+
+.. literalinclude:: ../../defaults/main.yml
+   :language: yaml
+   :start-after: under the License.
+
+
+Required Variables
+==================
+
+This list is not exhaustive at present. See role internals for further
+details.
+
+.. code-block:: yaml
+
+    # hostname or IP of load balancer providing external network
+    # access to Keystone
+    external_lb_vip_address: 10.100.100.102
+
+    # hostname or IP of load balancer providing internal network
+    # access to Keystone
+    internal_lb_vip_address: 10.100.100.102
+
+    # password used by the keystone service to interact with Galera
+    keystone_container_mysql_password: "YourPassword"
+
+    keystone_auth_admin_token: "SuperSecreteTestToken"
+    keystone_auth_admin_password: "SuperSecretePassword"
+    keystone_service_password: "secrete"
+    keystone_rabbitmq_password: "secrete"
+    keystone_container_mysql_password: "SuperSecrete"
+
+Example Playbook
+================
 
 ..  code-block:: yaml
 
@@ -17,4 +49,21 @@ This role will install the following:
       roles:
         - { role: "os_keystone", tags: [ "os-keystone" ] }
       vars:
-        keystone_galera_address: "{{ internal_lb_vip_address }}"
+        external_lb_vip_address: 10.100.100.102
+        internal_lb_vip_address: 10.100.100.102
+        keystone_galera_address: 10.100.100.101
+        keystone_galera_database: keystone
+        keystone_venv_tag: "testing"
+        keystone_developer_mode: true
+        keystone_git_install_branch: a55128044f763f5cfe2fdc57c738eaca97636448
+        keystone_auth_admin_token: "SuperSecreteTestToken"
+        keystone_auth_admin_password: "SuperSecretePassword"
+        keystone_service_password: "secrete"
+        keystone_rabbitmq_password: "secrete"
+        keystone_container_mysql_password: "SuperSecrete"
+        keystone_rabbitmq_port: 5671
+        keystone_rabbitmq_userid: keystone
+        keystone_rabbitmq_vhost: /keystone
+        keystone_rabbitmq_servers: 10.100.100.101
+        keystone_rabbitmq_use_ssl: true
+        galera_client_drop_config_file: false

defaults/main.yml

@@ -165,12 +165,11 @@ keystone_ssl_cipher_suite: "{{ ssl_cipher_suite|default('ECDH+AESGCM:DH+AESGCM:E
 keystone_ssl_self_signed_regen: false
 keystone_ssl_self_signed_subject: "/C=US/ST=Texas/L=San Antonio/O=IT/CN={{ internal_lb_vip_address }}/subjectAltName=IP.1={{ external_lb_vip_address }}"
 
-# Set these in user_variables to deploy custom certificates
+# Set these variables to deploy custom certificates
 #keystone_user_ssl_cert: <path to cert on ansible deployment host>
 #keystone_user_ssl_key: <path to cert on ansible deployment host>
 #keystone_user_ssl_ca_cert: <path to cert on ansible deployment host>
 
-
 # Set to true when terminating SSL/TLS at a load balancer
 keystone_external_ssl: false
 
@@ -349,6 +348,9 @@ keystone_sp_apt_packages:
 # Keystone notification settings
 keystone_ceilometer_enabled: false
 
+# These variables are used in 'developer mode' in order to allow the role
+# to build an environment directly from a git source without the presence
+# of an OpenStack-Ansible repo_server.
 keystone_git_repo: https://git.openstack.org/openstack/keystone
 keystone_git_install_branch: master
 keystone_developer_mode: false

doc/source/index.rst

@@ -1,14 +1 @@
-os_keystone Docs
-=============
-
-Tell us what the role is supposed to do?
-
-Basic Role Example
-^^^^^^^^^^^^^^^^^^
-
-Tell us how to use the role.
-
-.. code-block:: yaml
-
-    - role: "$ROLENAME"
-      ROLE_VARS...
+.. include:: ../../README.rst