diff --git a/plugins/inventory/openstack.py b/plugins/inventory/openstack.py
index c49d3c1fc43..92a81ac0e9d 100755
--- a/plugins/inventory/openstack.py
+++ b/plugins/inventory/openstack.py
@@ -17,6 +17,22 @@
 # You should have received a copy of the GNU General Public License
 # along with this software.  If not, see <http://www.gnu.org/licenses/>.
 
+# The OpenStack Inventory module uses os-client-config for configuation.
+# https://github.com/stackforge/os-client-config
+# This means it will either:
+#  - Respect normal OS_* environment variables like other OpenStack tools
+#  - Read values from a clouds.yaml file.
+# If you want to configure via clouds.yaml, you can put the file in:
+#  - Current directory
+#  - ~/.config/openstack/clouds.yaml
+#  - /etc/openstack/clouds.yaml
+#  - /etc/ansible/openstack.yml
+# The clouds.yaml file can contain entries for multiple clouds and multiple
+# regions of those clouds. If it does, this inventory module will connect to
+# all of them and present them as one contiguous inventory.
+#
+# See the adjacent openstack.yml file for an example config file
+
 import argparse
 import collections
 import os
diff --git a/plugins/inventory/openstack.yml b/plugins/inventory/openstack.yml
new file mode 100644
index 00000000000..a99bb020580
--- /dev/null
+++ b/plugins/inventory/openstack.yml
@@ -0,0 +1,28 @@
+clouds:
+  mordred:
+    cloud: hp
+    auth:
+      username: mordred@example.com
+      password: my-wonderful-password
+      project_name: mordred-tenant
+    region_name: region-b.geo-1
+  monty:
+    cloud: hp
+    auth:
+      username: monty.taylor@example.com
+      password: another-wonderful-password
+      project_name: monty.taylor@example.com-default-tenant
+    region_name: region-b.geo-1
+  rax:
+    cloud: rackspace
+    auth:
+      username: example
+      password: spectacular-password
+      project_id: 2352426
+    region_name: DFW,ORD,IAD
+  devstack:
+    auth:
+      auth_url: http://127.0.0.1:35357/v2.0/
+      username: stack
+      password: stack
+      project_name: stack