From ce2b05373a7691e36af79ee4939caf828b573c51 Mon Sep 17 00:00:00 2001
From: Matthew Treinish <mtreinish@kortar.org>
Date: Wed, 3 Aug 2016 15:54:49 -0400
Subject: [PATCH] Add docs for firehose.o.o

This commit adds docs for the firehose service.

Change-Id: I0406cf9cd5650f21cf02f2a34ad70184e2d989ae
---
 doc/source/firehose.rst | 58 +++++++++++++++++++++++++++++++++++++++++
 doc/source/systems.rst  |  1 +
 2 files changed, 59 insertions(+)
 create mode 100644 doc/source/firehose.rst

diff --git a/doc/source/firehose.rst b/doc/source/firehose.rst
new file mode 100644
index 0000000000..bf0a906dff
--- /dev/null
+++ b/doc/source/firehose.rst
@@ -0,0 +1,58 @@
+:title: Firehose
+
+.. _firehose:
+
+Firehose
+########
+
+The unified message bus for Infra services.
+
+At a Glance
+===========
+
+:Hosts:
+  * firehose*.openstack.org
+:Puppet:
+  * https://git.openstack.org/cgit/openstack-infra/puppet-mosquitto
+  * https://git.openstack.org/cgit/openstack-infra/puppet-germqtt
+  * :file:`modules/openstack_project/manifests/firehose.pp`
+:Projects:
+  * https://mosquitto.org/
+  * http://git.openstack.org/cgit/openstack-infra/germqtt/
+
+Overview
+========
+
+The firehose is an infra run MQTT broker that is a place for any infra run
+service to publish events to. The concept behind it is that if anything needs
+to consume an event from an infra run service we should have a single place
+to go for consuming them.
+
+firehose.openstack.org hosts an instance of Mosquitto to be the MQTT broker
+and also locally runs an instance of germqtt to publish the gerrit event
+stream over MQTT.
+
+Connection Info
+---------------
+
+firehose.openstack.org has 2 open ports for MQTT traffic:
+
+ * **1883** - The default MQTT port
+ * **80** - Uses websockets for the MQTT communication
+
+Topics
+------
+
+Topics at a top level are set based on the name of the service publishing the
+messages. The higher levels are specified by the publisher. For example::
+
+    gerrit/openstack-infra/germqtt/comment-added
+
+is a typical message topic on firehose. The top level 'gerrit' specifies the
+service the message is from, and the rest of the message comes from germqtt
+(the daemon used for publishing the gerrit events)
+
+MQTT topics are hierarchical and you can filter your subscription on part of the
+hierarchy. `[1]`_
+
+.. _[1]: https://mosquitto.org/man/mqtt-7.html
diff --git a/doc/source/systems.rst b/doc/source/systems.rst
index 52c0e194a2..31960276d7 100644
--- a/doc/source/systems.rst
+++ b/doc/source/systems.rst
@@ -38,6 +38,7 @@ Major Systems
    refstack
    codesearch
    signing
+   firehose
 
 .. NOTE(dhellmann): These projects were not listed above, or in any
    other toctree, which breaks the build. It's not clear why they were