Draft: Resolve "Provide tooling to migrate an active cluster from Operator Istio to Helm Istio."

See: #2283

docs/guides/using-bigbang/migrating-istio-in-bb3.0.md

@@ -2,29 +2,31 @@
 
 ### *The new Istio Helm packages are BETA in Big Bang 2.x and will be stable in 3.0*
 
-### Step 1 : Remove Istio from your deployment
-Before upgrading to version 3.0 of Big Bang with the new Helm-based Istio packages, we first need to disable Istio and Istio's Operator packages in our 2.x deployment of Big Bang. We do this by disabling the two obsolete [Istio packages in our Gitops configuration](https://repo1.dso.mil/kipten/template/-/blob/main/package-strategy/configmap.yaml?ref_type=heads#L18-22).
+### Step 1 : Remove Istio from your current deployment
+Before upgrading to the new Helm-based Istio packages, first disable the Istio and Istio's Operator packages:
 ```yaml
 istio:
   enabled: false
 istioOperator:
   enabled: false
 ```
-After a few minutes, all pods in both the `istio-system` and `istio-operator` namespaces should have terminated. However, due due to Istio's finalizer, it's likely that the `istio-system` namespace will be stuck in the `terminating` state. We can force the deletion of this namespace with the following:
+After a few minutes, all pods in both the `istio-system` and `istio-operator` namespaces will have terminated. However, due due to Istio's finalizer, the `istio-system` namespace will be stuck in the `terminating` state.  
+  
+Force the deletion of this namespace:
 ```bash
 kubectl get ns istio-system -o json | jq '.spec.finalizers = []' | kubectl replace --raw "/api/v1/namespaces/istio-system/finalize" -f -
 ```
-Both namespaces are now removed yet other remnants of Istio still linger in the cluster including custom resources. These also need to be removed as they will be re-instantiated via the helm deployment of Istio. There are various methods to accomplish this feat, but by far the easiest way to do this is by using the [istioctl CLI tool](https://istio.io/latest/docs/ops/diagnostic-tools/istioctl/).  
+Both Istio namespaces are now removed yet other remnants of Istio still linger in the cluster including custom resources. Remove them as they will be recreated via the helm deployment of Istio. The quickest way to do this is by using the [istioctl CLI tool](https://istio.io/latest/docs/ops/diagnostic-tools/istioctl/).  
   
-If you're on Mac or Linux, you can quickly install it with:
+If you're on Mac or Linux, you can install it with:
 ```bash
 brew install istioctl
 ```
-To complete the removal of the Istio remnants, purge [as per Istio's documentation](https://istio.io/latest/docs/setup/install/istioctl/#uninstall-istio):
+To complete the removal of remaining Istio components, purge as per [Istio's documentation](https://istio.io/latest/docs/setup/install/istioctl/#uninstall-istio):
 ```bash
 istioctl uninstall --purge
 ```
-Accept the prompt and these remnants are removed:
+Accept the prompt to proceed:
 ```bash
 All Istio resources will be pruned from the cluster
 Proceed? (y/N) y
@@ -55,14 +57,12 @@ Proceed? (y/N) y
 ✔ Uninstall complete 
 ```
 
-### Step 2 : Deploy the new Helm based version of Istio
-Enabling the Helm based version of Istio entails enabling the `istioCore` package that provides both the `istio-base` and `istiod` charts. The `istioGatewayPublic` package provides the default ingress gateway for most packages and the `istioGatewayPassthrough` provides a secondary non-TLS gated gateway for specific apps that require this like Keycloak.
+### Step 2 : Deploy the new Helm Istio package
+Enabling the Helm based version of Istio entails enabling the `istioCore` package that provides both the `istio-base` and `istiod` charts. The `istioGateway` package provides the ability to add one or more egress gateways:
 ```yaml
 istioCore:
   enabled: true
-istioGatewayPublic:
-  enabled: true
-istioGatewayPassthrough:
+istioGateway:
   enabled: true
 ```
 You can check that new gateway recieves an external IP (from MetalLB or AWS LB) with: