Merge pull request #16 in PAR/yap from DEV-3068-write-up-a-document-on-converting-yap-to-6.5 to master

* commit '7ce9202e5aaa6cf8240d3997c978e2f8dfdec079':
  Note minimum version for migrating off YAP
  Fix formatting typo in documentation
  Add documentation on migrating to managed mesh

README.rst

@@ -396,3 +396,169 @@ no arguments to see what actions are available::
 	region-add <region>
 	...
 
+
+Migrating a YAP space to a managed mesh space
+-----------------------------------------------
+
+As of 6.5, a successor to YAP is properly available in bonding in the form
+of the new private WAN modes (without PWRs) along with aggregator
+interfaces, addresses, and protocols.
+
+Migrating to managed mesh or unmanaged private WAN is required for continued
+support, and can be done with minimal downtime given the appropriate preparation.
+
+.. note::
+
+    To migrate a space to YAP, all aggregators carrying space traffic must be
+    upgraded to bonding version 6.5 or later.
+
+
+Preface
+============
+
+Recall that YAP has the following sets of objects::
+
+    A (aggregators)
+    D (device names)
+    R (regions)
+    S (spaces)
+    VID (VLAN IDs)
+    IP (PWAN IPs)
+
+and that these objects are related by the following functions::
+
+    r: A → R
+    d: A → D
+    v: S x R → VID
+    i: S x A → IP
+
+Given these sets and maps, YAP works by doing the following for each space *s*
+and aggregator *a*:
+
+#. Create a VLAN interface on *d(a)* having VLAN ID *v(s, r(a))*
+#. Add address *i(s, a)* to that VLAN interface.
+#. Run OSPF on that VLAN interface.
+
+Additionally, optional custom BIRD configuration can be defined for a space on a
+particular aggregator, i.e. there is an optional YAP object::
+
+    B (Custom space BIRD configuration)
+
+with relation::
+
+    b: S x A → B
+
+To migrate from YAP to a managed mesh, we need to recreate the same objects,
+i.e. for each space *s* and aggregator *a* we need to:
+
+0. Create trunk interface *d(a)* on aggregator *a*
+   (this only needs to be done once for *a*).
+#. Create a VLAN interface on *d(a)* with VID *v(s, r(a))*.
+#. Add interface IP *i(s, a)* to that VLAN interface.
+#. Create an OSPF protocol configured to have an area with that VLAN interface.
+
+Preparation
+================
+
+The instructions in this section are for preparing to migrate from YAP to
+managed mesh for a single private WAN space, one aggregator at a time.
+
+Let **S** be the YAP space to be migrated,
+let **A** be the aggregator to be migrated,
+and let **R** be the region **A** belongs to.
+
+.. tip::
+
+    All YAP commands given are run on the management server,
+    and all aggregator objects (interfaces, addresses, and protocols)
+    are created through the management server on the aggregator details
+    page.
+
+
+1. Create an Ethernet interface on **A** for the trunk interface configured in
+   YAP (if it is not already created).
+
+
+.. tip::
+
+   You can find the configured trunk interface for **A** with the YAP command::
+
+    yap agg-show <agg ID>
+
+   Look for the *trunk* value.
+
+
+2. Create a VLAN device on aggregator **A** having the interface created in the
+   previous step as the trunk, and having the VLAN ID configured in YAP for
+   **S** in **R** as the ID.
+
+   Configure the interface to be associated with space **S**.
+
+.. tip::
+
+   You can find the configured VLAN ID for **S** in **R** with the following YAP
+   command::
+
+    yap space-show <S key>
+
+   Below *VLAN associations*, look for **R** followed by the VLAN ID.
+
+
+3. Add an address to the VLAN interface created in the previous step,
+   using the IP configured by YAP for **S** on **A**.
+
+.. tip::
+
+   You can find the configured IP for **S** on **A** with the following YAP
+   command::
+
+    yap subnet-get <S key> <R>
+
+    Below `Aggregators`, look for **A** followed by the IP.
+
+
+4. Create an OSPF protocol on aggregator **A** with the following configuration.
+   Anything not specified should be left to its default value in the form.
+
+    - Name: mm_<space key>
+    - Space: <space>
+    - Protocol: OSPF
+    - Enable: Off
+    - IPv4 import: All
+    - IPv4 export All
+    - Channel: IPv4
+    - Area:
+        - Area ID: 0.0.0.0
+        - Interface:
+            - Pattern: <name of VLAN created in step 2>
+
+   Click 'add area' to open the area form for configuring the Area ID,
+   and click 'add interface' to open the interface form to add the interface
+   pattern.
+
+.. warning::
+
+    If you do not set *Enabled* off, you may unintentionally affect private
+    WAN traffic prematurely.
+
+
+Migration
+=========================
+
+One the prepartion steps have been done for every aggregator carrying space
+traffic, the space is ready to be migrated to managed mesh.
+
+.. warning::
+
+    There will be a brief space outage during the migration.
+
+To actually perform the migration, three things must be done:
+
+#. Delete the space in YAP:
+    #. For each region, run *yap vlan-remove <space> <region>*
+    #. Run *yap space-delete <space>*
+#. Change the space mode from 'with private WAN routers' to 'managed mesh'
+#. Enable all the protocols created during the preparation phase.
+
+Confirm these protocols peer with any upstream neighbors in each region and that
+private WAN routes are being propogated.