[VOL-3634] Adding multi-stack support docs
Change-Id: I290ca9b2e9ee73c96010b53493144da728377f01
diff --git a/VERSION b/VERSION
index 437459c..8f87ff7 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-2.5.0
+2.6.0-dev
diff --git a/overview/deployment_environment.rst b/overview/deployment_environment.rst
index 44f877f..45f3b9a 100644
--- a/overview/deployment_environment.rst
+++ b/overview/deployment_environment.rst
@@ -60,6 +60,7 @@
./lab_setup.rst
./pod_physical.rst
./dev_virtual.rst
+ ./multi-stack.rst
Tooling
-------
diff --git a/overview/multi-stack.rst b/overview/multi-stack.rst
new file mode 100644
index 0000000..3ce4c3d
--- /dev/null
+++ b/overview/multi-stack.rst
@@ -0,0 +1,95 @@
+Deploy multiple VOLTHA stacks on a Kubernetes cluster
+=====================================================
+
+VOLTHA is designed so that multiple stacks can work together sharing the same infrastructure.
+You can read more about VOLTHA Stacks in this `document <https://docs.google.com/document/d/1Szo7vMS7M96O4Vsm1NpDYd3zckk9g0HLMck6eldwmcI/edit?usp=sharing>`_.
+
+This guide assumes you have a ``kubernetes`` cluster already up and running.
+We also assume you have familiarity with the `kind-voltha <../kind-voltha/README.html>`_. tool.
+
+Deploy the common infrastructure
+--------------------------------
+
+When we refer to `infrastructure` components in VOLTHA, we are referring to:
+
+- ``Kafka``
+- ``ETCD``
+- ``ONOS``
+- ``RADIUS Server`` (optional)
+- ``Sadis Server`` (optional)
+
+*Note that these components can be deployed on ``kubernetes`` via ``kind-voltha`` or can be completely independent.*
+
+.. code:: bash
+
+ NAME=infra INFRA_NS=infra JUST_INFRA=y ./voltha up
+
+Note that this command will output configurations that you'll need to deploy your ``VOLTHA`` stack:
+
+.. code:: bash
+
+ To configure your VOLTHA stack to use this infrastructure please export these variables:
+ export INFRA_NS=infra
+ export WITH_ETCD=etcd.infra.svc:2379
+ export WITH_KAFKA=kafka.infra.svc:9092
+ export WITH_ONOS=onos-onos-classic-hs.infra.svc:6653
+
+ Or use:
+
+ INFRA_NS=infra WITH_ETCD=etcd.infra.svc:2379 WITH_KAFKA=kafka.infra.svc:9092 WITH_ONOS=onos-onos-classic-hs.infra.svc:6653 ./voltha up
+
+ If you are deploying mutltiple VOLTHA stack, also remember to configure a different NAME, NAMESPACE and BBSIM_BASE_INDEX for each stack:
+ export NAME=voltha1
+ export VOLTHA_NS=voltha1
+ export ADAPTER_NS=voltha1
+ export BBSIM_NS=voltha1
+ export BBSIM_BASE_INDEX=1
+
+ Or use:
+
+ INFRA_NS=infra WITH_ETCD=etcd.infra.svc:2379 WITH_KAFKA=kafka.infra.svc:9092 WITH_ONOS=onos-onos-classic-hs.infra.svc:6653 NAME=voltha1 VOLTHA_NS=voltha1 ADAPTER_NS=voltha1 BBSIM_NS=voltha1 BBSIM_BASE_INDEX=1 ./voltha up
+
+Deploy a VOLTHA stack
+---------------------
+
+Once the ``infrastructure`` is set up you can deploy a ``VOLTHA`` stack using this command:
+
+.. code:: bash
+
+ NAME=voltha1 VOLTHA_NS=voltha1 ADAPTER_NS=voltha1 BBSIM_NS=voltha1 BBSIM_BASE_INDEX=1 ./voltha up
+
+NOTE that this command assumes you have exported the variables printed at the end of the ``infra`` deployment.
+In particular the required variables are:
+
+- ``INFRA_NS=infra`` (optional) only required if you installed the infrastructure using ``kind-voltha``
+- ``WITH_ETCD=etcd.infra.svc:2379`` the ETCD address
+- ``WITH_KAFKA=kafka.infra.svc:9092`` the KAFKA address
+- ``WITH_ONOS=onos-onos-classic-hs.infra.svc:6653`` the ONOS address
+
+Deploying multiple VOLTHA stacks
+********************************
+
+When you deploy a second ``VOLTHA`` stack there are some information that you need to customize in order to keep the
+two stacks independent:
+
+- ``NAME`` - the name of the stack, is used in log and configuration files and to customize the KAFKA topics each stack
+ is listening on
+- ``VOLTHA_NS, ADAPTER_NS, BBSIM_NS`` - are used to configure in which namespace the components are installed
+- ``BBSIM_BASE_INDEX`` - is used to guarantee that different ``BBSim`` instances won't have the same ID (have to be
+ unique across all the stacks)
+
+Operate a VOLTHA stack
+----------------------
+
+Once the installation completes a ``voltctl`` config file is generated for each cluster, in the format:
+
+.. code:: bash
+
+ VOLTCONFIG="~/.volt/config-<$NAME>"
+
+In order to use multiple stacks via the same ``voltcl`` tools we **strongly** suggest to **always** specify
+the appropriate configuration with the ``-c`` flag, for example:
+
+.. code:: bash
+
+ voltctl -c ~/.volt/config-voltha1 adapter list
diff --git a/release_notes/voltha_2.5.rst b/release_notes/voltha_2.5.rst
index dde26e5..f2b6d74 100644
--- a/release_notes/voltha_2.5.rst
+++ b/release_notes/voltha_2.5.rst
@@ -43,7 +43,7 @@
Test
----
-Voltha-2.5 tests are available on `Jenkins <https://jenkins.opencord.org/view/VOLTHA%202.5/>`_.
+Voltha-2.5 tests are available on `Jenkins <https://jenkins.opencord.org/>`_.
- OLT Disable/enable test, ONOS HA test and some more
- BBSim Turk Telekom workflow support