===========================================================
Migrating from using private WAN routers to a managed mesh
===========================================================

Prerequisites
-------------

A private WAN-enabled space configured with:

* dedicated gateway via PWAN router,
* dedicated gateway via bonder, or
* no gateways

.. note::

    Migrating a space with NAT via PWAN router and NAT/port forward rules
    requires additional configuration on an external gateway/firewall as
    managed mesh does not support NAT. To migrate a space using NAT, the first
    step is to move the NAT responsibility to an external gateway/firewall,
    then migrate the space to a dedicated gateway via PWAN router, and finally,
    follow the below documentation to complete the migration to managed mesh.

Expected downtime
-----------------

The following instructions allow for preconfiguring the required interfaces,
IP addresses, and routing protocols. Once the requirements are in place, switching
the space to managed mesh may be done in a matter of minutes.

However, depending on the complexity of the space's gateways and number of aggregators
involved, we recommend a **30-60 minute outage window** be secured for any migrations.

Static vs dynamic routing
-------------------------

Private WAN routers had limited support for dynamic routing and only supported
dynamic routing of NAT via PWAN router gateways and NAT/port forward rules.

Managed mesh has expanded support for dynamic routing which will be used in
this guide. If dynamic routing isn't supported in the datacentre, static routing
may still be used to migrate to managed mesh.

VLAN interfaces
---------------

In the private WAN router mode, a VLAN trunk interface was configured on each
private WAN router when installing bonding, through the `pwan-configure-networking`
script. Gateways for private WAN spaces were then assigned a VLAN tag.

In managed mesh, a VLAN interface is added to one or more aggregators as required.

Migrating a dedicated gateway via PWAN router
---------------------------------------------

Preparation
^^^^^^^^^^^

To migrate a space with a dedicated gateway via PWAN router gateway to use managed
mesh, *at least* one aggregator must be configured with a VLAN interface, IP address,
and routing protocol.

While the minimum requirement is for one aggregator to be configured in this way,
configuring two or more aggregators with dynamic routing protocols will ensure
routing is not affected by a single aggregator failure.

As an example, suppose a space is configured with a *dedicated gateway via PWAN router*
as follows:

|dgw_via_pwr|

To start, designate an aggregator in the routing group *rg1* to be used as the gateway
in place of the private WAN router. Start by adding a VLAN interface to this aggregator,
with an IP in the same subnet as the dedicated gateway via PWAN router. Select the
appropriate space from the drop-down menu to isolate traffic on this interface to that space.

|dgw_via_pwr_a1_iif|

Next, configure a protocol on this same aggregator. By choosing the same space as for
the VLAN interface above, the aggregator will automatically import and export routes
on this isolated interface.

|dgw_via_pwr_space_proto|

.. warning::

    Enabling the protocol at this point may cause an outage if the peer exports a route
    to the aggregator such that traffic would flow via the aggregator instead of the
    private WAN router. It is recommended to disable the protocol until the migration
    window.

In this example, OSPF was chosen as the dynamic routing protocol. Choosing a dynamic
routing protocol (OSPF, BGP, or Babel) for the space protocols will allow for seamless
movement of bonds between aggregators without the need to update static routes. For
those accustomed to setting up these dynamic routing protocols, the configuration
options found in the GUI will be familiar.

At this point, the preparation is complete. The steps above may be repeated for more
aggregators, and in particular, may be necessary for other routing groups to provide
localized ingress/egress to a space.

Final migration
^^^^^^^^^^^^^^^

To make the transition, update the space's private WAN mode to be
"Managed mesh" and enable any aggregator protocols that were initially disabled.

The management server will automatically send out the required configuration updates
to stop the space from running on the private WAN routers and start the interfaces,
IP address(es), and protocols. The managed mesh will also automatically establish,
providing routing between aggregators that host bonds in the space.

Migrating a dedicated gateway via bonder
----------------------------------------

Preparation
^^^^^^^^^^^

To migrate a dedicated gateway via bonder to a managed mesh, we need to
configure the bonder with a `protocol <../../dynamic-routing/configuring-dynamic-routing-in-bonding.html>`__
instead of the aggregator.

Dynamic routing protocols may be used on bonder protocols as well, but this example
shows how a static routing protocol could directly emulate the behavior of the
dedicated gateway via bonder.

For example, if the bonder has a connected IP of 192.168.1.2/24 (in private WAN)
and the gateway is at 192.168.1.1, we might add the following protocol
on the bonder:

|dgw_via_bnr_a1_proto|

Note the protocol is included in private WAN, and disabled initially to avoid
interfering with private WAN traffic before making the switch.

Final migration
^^^^^^^^^^^^^^^

To make the transition, simply update the space's private WAN mode to be
"Managed mesh" and enable any bonder protocols that were initially disabled.

The management server will automatically send out the required configuration updates
to stop the space from running on the private WAN routers and start the bonder protocol.
The managed mesh will also automatically establish, providing routing between aggregators
that host bonds in the space.

Migrating NAT via PWAN router
------------------------------

The managed mesh **does not NAT traffic** or support routing PWAN traffic that
has been NAT'ed. Hence, spaces using *NAT via PWAN router* cannot be directly
migrated -- the upstream gateway/firewall must first be configured to NAT the
PWAN traffic.

First, the space should be (effectively) transitioned from
*NAT via PWAN router* to *Dedicated gateway via PWAN router*,
and then from there migrated as detailed `above
<migrating.html#migrating-a-dedicated-gateway-via-pwan-router>`__.

.. |dgw_via_pwr| image:: /attachments/spaces/dgw_via_pwr.png
.. |dgw_via_pwr_a1_iif| image:: /attachments/spaces/dgw_via_pwr_a1_iif.png
.. |dgw_via_pwr_space_proto| image:: /attachments/spaces/dgw_via_pwr_space_proto.png
.. |dgw_via_bnr_a1_proto| image:: /attachments/spaces/dgw_via_bnr_a1_proto.png

.. _`private WAN tab`: /docs/spaces/space-private-wan.html#space-private-wan
