From 7d3cce02c3a5f4f88a24e2feb47865c3fc5da227 Mon Sep 17 00:00:00 2001
From: Robb Romans <robb.romans@rackspace.com>
Date: Thu, 11 Aug 2016 12:51:49 -0500
Subject: [PATCH] [DOCS] Move RabbitMQ role docs

Update the role documentation to match the new format. Each role project
should maintain the configuration variations for the role project
itself.

Change-Id: I73b061da40b08b327fc3445e073cbd8997920ccd
---
 README.rst                        | 39 ++++++-------------------------
 doc/source/configure-rabbitmq.rst | 36 ++++++++++++++++++++++++++++
 doc/source/index.rst              | 37 ++++++++++++++++++++++++++++-
 examples/playbook.yml             |  7 ++++++
 4 files changed, 86 insertions(+), 33 deletions(-)
 create mode 100644 doc/source/configure-rabbitmq.rst
 create mode 100644 examples/playbook.yml

diff --git a/README.rst b/README.rst
index b6dd9294..582d70a0 100644
--- a/README.rst
+++ b/README.rst
@@ -1,34 +1,9 @@
-OpenStack-Ansible RabbitMQ Server
-#################################
+=================================
+OpenStack-Ansible RabbitMQ server
+=================================
 
-This Ansible role deploys RabbitMQ. When multiple hosts are present in the
-rabbitmq_all inventory group a cluster will be created.
-
-Default Variables
-=================
-
-.. literalinclude:: ../../defaults/main.yml
-   :language: yaml
-   :start-after: under the License.
-
-Required Variables
-==================
-
-.. code-block:: yaml
-
-    # RabbitMQ cluster shared secret
-    rabbitmq_cookie_token: secrete
-
-Example Playbook
-================
-
-.. code-block:: yaml
-
-    - name: Install rabbitmq server
-      hosts: rabbitmq_all
-      user: root
-      roles:
-        - { role: "rabbitmq_server", tags: [ "rabbitmq-server" ] }
-      vars:
-        rabbitmq_cookie_token: secrete
+Documentation for the project can be found at:
+  http://docs.openstack.org/developer/openstack-ansible-rabbitmq_server
 
+The project home is at:
+  http://launchpad.net/openstack-ansible
diff --git a/doc/source/configure-rabbitmq.rst b/doc/source/configure-rabbitmq.rst
new file mode 100644
index 00000000..b8d2d24e
--- /dev/null
+++ b/doc/source/configure-rabbitmq.rst
@@ -0,0 +1,36 @@
+===============================
+Scenario - Configuring RabbitMQ
+===============================
+
+RabbitMQ provides the messaging broker for various OpenStack services.
+The OpenStack-Ansible project configures a plain text listener on port
+5672 and a SSL/TLS encrypted listener on port 5671.
+
+Customize your RabbitMQ deployment in
+``/etc/openstack_deploy/user_variables.yml``.
+
+Add a TLS encrypted listener to RabbitMQ
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The OpenStack-Ansible project provides the ability to secure RabbitMQ
+communications with self-signed or user-provided SSL certificates.
+Refer to "Securing services with SSL certificates" in the OSA Install
+Guide for available configuration options.
+
+Enable encrypted connections to RabbitMQ
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The control of SSL communication between various OpenStack services
+and RabbitMQ is via the Ansible variable ``rabbitmq_use_ssl``:
+
+.. code-block:: yaml
+
+   rabbitmq_use_ssl: true
+
+Setting this variable to ``true`` adjusts the RabbitMQ port to 5671
+(the default SSL/TLS listener port) and enables SSL connectivity
+between each OpenStack service and RabbitMQ.
+
+Setting this variable to ``false`` disables SSL encryption between
+OpenStack services and RabbitMQ and configures all services to
+use the plain text port, 5672.
diff --git a/doc/source/index.rst b/doc/source/index.rst
index a6210d3d..b33b1b79 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1 +1,36 @@
-.. include:: ../../README.rst
+=================================
+OpenStack-Ansible RabbitMQ server
+=================================
+
+This Ansible role deploys RabbitMQ. When multiple hosts are present in
+the ``rabbitmq_all`` inventory group, a cluster is created.
+
+Table of Contents
+~~~~~~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 2
+
+   configure-rabbitmq.rst
+
+
+Default variables
+~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../defaults/main.yml
+   :language: yaml
+   :start-after: under the License.
+
+Required variables
+~~~~~~~~~~~~~~~~~~
+
+.. code-block:: yaml
+
+    # RabbitMQ cluster shared secret
+    rabbitmq_cookie_token: secrete
+
+Example playbook
+~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../examples/playbook.yml
+   :language: yaml
diff --git a/examples/playbook.yml b/examples/playbook.yml
new file mode 100644
index 00000000..d6dac3e4
--- /dev/null
+++ b/examples/playbook.yml
@@ -0,0 +1,7 @@
+- name: Install RabbitMQ server
+  hosts: rabbitmq_all
+  user: root
+  roles:
+    - { role: "rabbitmq_server", tags: [ "rabbitmq-server" ] }
+  vars:
+    rabbitmq_cookie_token: secrete