From ca3d3f619bc58fdaf105b934451fe286e083e431 Mon Sep 17 00:00:00 2001
From: Peter Matulis <peter.matulis@canonical.com>
Date: Mon, 22 Jun 2020 16:56:34 -0400
Subject: [PATCH] Add section for feature supportability

Change-Id: I7bcb11778a56bf9353b6675b68e7b4f2fbbdbdec
---
 doc/source/index.rst         |  1 +
 doc/source/support-notes.rst | 45 ++++++++++++++++++++++++++++++++++++
 2 files changed, 46 insertions(+)
 create mode 100644 doc/source/support-notes.rst

diff --git a/doc/source/index.rst b/doc/source/index.rst
index ba07204b..ee7af6a1 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -13,6 +13,7 @@ deployments with loose coupling between OpenStack services.
    find-us
    deployment
    openstack-charms
+   support-notes
    creating-charms
    how-to-contribute
    author-guides/index
diff --git a/doc/source/support-notes.rst b/doc/source/support-notes.rst
new file mode 100644
index 00000000..35cde5be
--- /dev/null
+++ b/doc/source/support-notes.rst
@@ -0,0 +1,45 @@
+.. _support-notes:
+
+=============
+Support notes
+=============
+
+This page describes supportability aspects within the OpenStack Charms project.
+
+Cross model relations
+---------------------
+
+Juju relations that are added between applications that reside in separate Juju
+models are called `Cross model relations`_ (CMR). For a Charmed OpenStack
+deployment, CMR support must also be present in terms of the manner in which
+the charms are combined. The OpenStack Charms do not generically support CMR.
+
+.. important::
+
+   It is recommended to exercise each new CMR scenario in a lab environment
+   before committing to that topology in production.
+
+The current list of supported CMR scenarios with regard to OpenStack Charms is
+as follows:
+
+#. The keystone application in one model, related to the vault application in a
+   second model.
+#. The ceph-mon application in one model, related to the ceph-rbd-mirror
+   application in a second model. This scenario is documented in `Ceph RBD
+   mirroring`_.
+#. A ceph-radosgw application in one model, related to another ceph-radosgw
+   application in a second model. This scenario is documented in `Ceph RADOS
+   Gateway multisite replication`_.
+
+Other scenarios may work but are currently not supported. Distinct development
+and testing efforts are required in order to qualify each unique CMR scenario.
+
+If you would like to help drive the development work towards implementing a
+supported CMR scenario file a Launchpad bug describing your use case. To assist
+in this effort kindly use the `cross-model`_ bug tag.
+
+.. LINKS
+.. _Cross model relations: https://juju.is/docs/cross-model-relations
+.. _cross-model: https://bugs.launchpad.net/bugs/+bugs?field.tag=cross-model
+.. _Ceph RBD Mirroring: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/app-ceph-rbd-mirror.html
+.. _Ceph RADOS Gateway Multisite replication: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/app-rgw-multisite.html