From 652fac552980430b37c675f2ca2273fbf52b9994 Mon Sep 17 00:00:00 2001
From: Mike Beaumont <mjboamail@gmail.com>
Date: Tue, 17 Sep 2024 12:53:16 +0200
Subject: [PATCH] docs(MeshService): add migration notes

Signed-off-by: Mike Beaumont <mjboamail@gmail.com>
---
 app/_src/networking/meshservice.md | 44 ++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/app/_src/networking/meshservice.md b/app/_src/networking/meshservice.md
index 1fe02827b..9c3e87f34 100644
--- a/app/_src/networking/meshservice.md
+++ b/app/_src/networking/meshservice.md
@@ -98,3 +98,47 @@ name of the `Dataplane` port.
     targetPort: 6739
     appProtocol: tcp
 ```
+
+## Migration
+
+MeshService is opt-in and involves a migration process. Every `Mesh` must enable
+`MeshServices` in some form:
+
+```
+spec:
+  meshServices:
+    enabled: Disabled # or Everywhere, ReachableBackendRefs, Exclusive
+```
+
+Remember that the biggest change with `MeshService` is that traffic is no longer
+load-balancing between all zones. Traffic sent to a `MeshService` is only ever
+sent to a single zone.
+
+You may be using `kuma.io/service` to split traffic across zones. Part of
+migrating is deciding for every `kuma.io/service`, whether traffic should be
+limited to one zone, so using a `MeshService`, or load-balancing, which
+means using `MeshMultiZoneService`.
+
+After enabling `MeshServices`, the control plane generates additional resources.
+There are a few ways to manage this.
+
+### `Everywhere`
+
+This enables `MeshService` resource generation everywhere. This means twice as
+many Envoy Clusters and ClusterLoadAssignments. That in turn means potentially
+hitting the resource limits of the control plane, before reachable backends
+would otherwise be necessary. Therefore, consider trying `ReachableBackends` as
+described below.
+
+### `ReachableBackend`
+
+This enables automatic generation of the Kuma `MeshServices` resource but
+does not include the corresponding resources for every data plane proxy.
+The intention is for users to explicitly and gradually introduce
+relevant `MeshServices` via `reachableBackends`.
+
+### `Exclusive`
+
+This is the end goal of the migration. Destinations in the mesh are managed
+solely with `MeshService` resources and no longer via `kuma.io/service` tags and
+`Dataplane` inbounds.