From 715462753280b5b4b7104b3199d6e4a93379e863 Mon Sep 17 00:00:00 2001
From: Mike Kolesnik <mkolesni@redhat.com>
Date: Tue, 2 Dec 2025 18:22:20 +0200
Subject: [PATCH] fix(docs): Restore lost content from migration (#1418)

This commit fixes substantial content changes that were incorrectly
introduced during the markdown to AsciiDoc migration in commit
e8232064e38018c7b2b093787f87e3acf0b5b9ef. The fixes restore missing
content and correct broken links while preserving all changes made
after the migration commit.

Changes in docs/README.adoc:
- Fix broken internal link: changed guidelines.md to guidelines.adoc

Changes in docs/deployment-models/multicluster.adoc:

Primary-Remote - Single-Network section:
- Restore missing 'externalIstiod: true' in Istio resource on cluster1
- Restore missing step 2: Create east-west gateway on cluster1
- Restore missing step 3: Expose istiod on cluster1
- Fix remotePilotAddress: use istio-eastwestgateway ClusterIP instead
  of istiod LoadBalancer IP
- Restore missing istiodRemote.injectionPath configuration
- Restore missing step 5: Set control plane cluster annotation
- Fix remote secret name: change from 'cluster2' to 'remote'
- Restore missing kind-specific instructions for REMOTE_CONTAINER_IP
- Fix external links: restore primary-remote/ URLs (removed
  _single-network)
- Fix verification steps: restore single curl commands (removed loops)
- Fix cleanup order to match original
- Fix wait command format to match original (inline with apply)

Primary-Remote - Multi-Network section:
- Remove incorrectly added network label command
- Fix step title to match original

All fixes preserve later changes (e.g., version updates from commit
d2cbd963) and only revert unwanted changes from the migration commit.

Refs: e8232064e38018c7b2b093787f87e3acf0b5b9ef
Fixes: https://github.com/istio-ecosystem/sail-operator/issues/1373

Signed-off-by: Mike Kolesnik <mkolesni@redhat.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 docs/README.adoc                         |  2 +-
 docs/deployment-models/multicluster.adoc | 97 +++++++++++++-----------
 2 files changed, 55 insertions(+), 44 deletions(-)

diff --git a/docs/README.adoc b/docs/README.adoc
index a7ca3003d..c69dbbba6 100644
--- a/docs/README.adoc
+++ b/docs/README.adoc
@@ -7,7 +7,7 @@
 
 link:../[Return to Project Root]
 
-*Note*: To add new topics to this documentation, please follow the guidelines in the link:../../docs/guidelines/guidelines.md[guidelines] doc.
+*Note*: To add new topics to this documentation, please follow the guidelines in the link:../../docs/guidelines/guidelines.adoc[guidelines] doc.
 
 == Table of Contents
 
diff --git a/docs/deployment-models/multicluster.adoc b/docs/deployment-models/multicluster.adoc
index f3f9775fe..ffc48f35d 100644
--- a/docs/deployment-models/multicluster.adoc
+++ b/docs/deployment-models/multicluster.adoc
@@ -518,9 +518,9 @@ kubectl delete ns sample --context="${CTX_CLUSTER2}"
 
 === Primary-Remote - Single-Network
 
-These instructions install a https://istio.io/latest/docs/setup/install/multicluster/primary-remote_single-network/[primary-remote/single-network] Istio deployment using the Sail Operator and Sail CRDs. **Before you begin**, ensure you complete the <<common-setup,common setup>>.
+These instructions install a https://istio.io/latest/docs/setup/install/multicluster/primary-remote/[primary-remote] Istio deployment using the Sail Operator and Sail CRDs. **Before you begin**, ensure you complete the <<common-setup,common setup>>.
 
-These installation instructions are adapted from: https://istio.io/latest/docs/setup/install/multicluster/primary-remote_single-network/.
+These installation instructions are adapted from: https://istio.io/latest/docs/setup/install/multicluster/primary-remote/.
 
 In this setup there is a Primary cluster (`cluster1`) and a Remote cluster (`cluster2`) which are on a single shared network.
 
@@ -541,16 +541,27 @@ spec:
       multiCluster:
         clusterName: cluster1
       network: network1
+      externalIstiod: true
 EOF
+kubectl wait --context "${CTX_CLUSTER1}" --for=jsonpath='{.status.revisions.ready}'=1 istios/default --timeout=3m
 ----
 
-. Wait for the control plane to become ready.
+. Create east-west gateway on `cluster1`.
++
+// TODO: Find a nicer way to deploy the actual service as ClusterIP, instead of patching it.
 +
 ----
-kubectl wait --context "${CTX_CLUSTER1}" --for=condition=Ready istios/default --timeout=3m
+kubectl apply --context "${CTX_CLUSTER1}" -f https://raw.githubusercontent.com/istio-ecosystem/sail-operator/main/docs/deployment-models/resources/east-west-gateway-net1.yaml
+kubectl --context "${CTX_CLUSTER1}" patch service istio-eastwestgateway -n istio-system -p '{"spec":{"type":"ClusterIP"}}'
 ----
 
-. Create an `Istio` resource on `cluster2` with the `remote` profile.
+. Expose istiod on `cluster1`.
++
+----
+kubectl apply --context "${CTX_CLUSTER1}" -f https://raw.githubusercontent.com/istio-ecosystem/sail-operator/main/docs/deployment-models/resources/expose-istiod.yaml
+----
+
+. Create an `Istio` on `cluster2` with the `remote` profile.
 +
 ----
 kubectl apply --context "${CTX_CLUSTER2}" -f - <<EOF
@@ -563,36 +574,45 @@ spec:
   namespace: istio-system
   profile: remote
   values:
+    istiodRemote:
+      injectionPath: /inject/cluster/cluster2/net/network1
     global:
-      meshID: mesh1
-      multiCluster:
-        clusterName: cluster2
-      network: network1
-      remotePilotAddress: $(kubectl --context="${CTX_CLUSTER1}" -n istio-system get svc istiod -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
+      remotePilotAddress: $(kubectl --context="${CTX_CLUSTER1}" -n istio-system get svc istio-eastwestgateway -o jsonpath='{.spec.clusterIP}')
 EOF
 ----
 
-. Install a remote secret in `cluster1` that provides access to the `cluster2` API server.
+. Set the control plane cluster for `cluster2`.
++
+----
+kubectl --context="${CTX_CLUSTER2}" annotate namespace istio-system topology.istio.io/controlPlaneClusters=cluster1
+----
+
+. Install a remote secret on `cluster1` that provides access to the `cluster2` API server.
 +
 ----
 istioctl create-remote-secret \
   --context="${CTX_CLUSTER2}" \
-  --name=cluster2 | \
+  --name=remote | \
   kubectl apply -f - --context="${CTX_CLUSTER1}"
 ----
 
-. Create sample application namespaces in each cluster.
++
+If using kind, first get the `cluster2` controlplane ip and pass the `--server` option to `istioctl create-remote-secret`
 +
 ----
-kubectl get ns sample --context "${CTX_CLUSTER1}" || kubectl create --context="${CTX_CLUSTER1}" namespace sample
-kubectl label --context "${CTX_CLUSTER1}" namespace sample istio-injection=enabled
-kubectl get ns sample --context "${CTX_CLUSTER2}" || kubectl create --context="${CTX_CLUSTER2}" namespace sample
-kubectl label --context "${CTX_CLUSTER2}" namespace sample istio-injection=enabled
+REMOTE_CONTAINER_IP=$(kubectl get nodes -l node-role.kubernetes.io/control-plane --context "${CTX_CLUSTER2}" -o jsonpath='{.items[0].status.addresses[?(@.type == "InternalIP")].address}')
+istioctl create-remote-secret \
+  --context="${CTX_CLUSTER2}" \
+  --name=remote \
+  --server="https://${REMOTE_CONTAINER_IP}:6443" | \
+  kubectl apply -f - --context="${CTX_CLUSTER1}"
 ----
 
-. Deploy sample applications in `cluster1`.
+. Deploy sample applications to `cluster1`.
 +
 ----
+kubectl get ns sample --context "${CTX_CLUSTER1}" || kubectl create --context="${CTX_CLUSTER1}" namespace sample
+kubectl label --context="${CTX_CLUSTER1}" namespace sample istio-injection=enabled
 kubectl apply --context="${CTX_CLUSTER1}" \
   -f "https://raw.githubusercontent.com/istio/istio/${ISTIO_VERSION}/samples/helloworld/helloworld.yaml" \
   -l service=helloworld -n sample
@@ -603,9 +623,11 @@ kubectl apply --context="${CTX_CLUSTER1}" \
   -f "https://raw.githubusercontent.com/istio/istio/${ISTIO_VERSION}/samples/sleep/sleep.yaml" -n sample
 ----
 
-. Deploy sample applications in `cluster2`.
+. Deploy sample applications to `cluster2`.
 +
 ----
+kubectl get ns sample --context "${CTX_CLUSTER2}" || kubectl create --context="${CTX_CLUSTER2}" namespace sample
+kubectl label --context="${CTX_CLUSTER2}" namespace sample istio-injection=enabled
 kubectl apply --context="${CTX_CLUSTER2}" \
   -f "https://raw.githubusercontent.com/istio/istio/${ISTIO_VERSION}/samples/helloworld/helloworld.yaml" \
   -l service=helloworld -n sample
@@ -616,46 +638,36 @@ kubectl apply --context="${CTX_CLUSTER2}" \
   -f "https://raw.githubusercontent.com/istio/istio/${ISTIO_VERSION}/samples/sleep/sleep.yaml" -n sample
 ----
 
-. Wait for the sample applications to be ready.
+. Verify that you see a response from both v1 and v2 on `cluster1`.
 +
-----
-kubectl --context="${CTX_CLUSTER1}" wait --for condition=available -n sample deployment/helloworld-v1
-kubectl --context="${CTX_CLUSTER2}" wait --for condition=available -n sample deployment/helloworld-v2
-kubectl --context="${CTX_CLUSTER1}" wait --for condition=available -n sample deployment/sleep
-kubectl --context="${CTX_CLUSTER2}" wait --for condition=available -n sample deployment/sleep
-----
-
-. From `cluster1`, send 10 requests to the helloworld service. Verify that you see responses from both v1 and v2.
+`cluster1` responds with v1 and v2
 +
 ----
-for i in {0..9}; do
-  kubectl exec --context="${CTX_CLUSTER1}" -n sample -c sleep \
+kubectl exec --context="${CTX_CLUSTER1}" -n sample -c sleep \
     "$(kubectl get pod --context="${CTX_CLUSTER1}" -n sample -l \
     app=sleep -o jsonpath='{.items[0].metadata.name}')" \
-    -- curl -sS helloworld.sample:5000/hello;
-done
+    -- curl -sS helloworld.sample:5000/hello
 ----
 
-. From `cluster2`, send another 10 requests to the helloworld service. Verify that you see responses from both v1 and v2.
++
+`cluster2` responds with v1 and v2
 +
 ----
-for i in {0..9}; do
-  kubectl exec --context="${CTX_CLUSTER2}" -n sample -c sleep \
+kubectl exec --context="${CTX_CLUSTER2}" -n sample -c sleep \
     "$(kubectl get pod --context="${CTX_CLUSTER2}" -n sample -l \
     app=sleep -o jsonpath='{.items[0].metadata.name}')" \
-    -- curl -sS helloworld.sample:5000/hello;
-done
+    -- curl -sS helloworld.sample:5000/hello
 ----
 
 . Cleanup
 +
 ----
-kubectl delete istios default --context="${CTX_CLUSTER1}"
-kubectl delete ns istio-system --context="${CTX_CLUSTER1}"
 kubectl delete ns sample --context="${CTX_CLUSTER1}"
-kubectl delete istios default --context="${CTX_CLUSTER2}"
-kubectl delete ns istio-system --context="${CTX_CLUSTER2}"
+kubectl delete ns istio-system --context="${CTX_CLUSTER1}"
+kubectl delete istios default --context="${CTX_CLUSTER1}"
 kubectl delete ns sample --context="${CTX_CLUSTER2}"
+kubectl delete ns istio-system --context="${CTX_CLUSTER2}"
+kubectl delete istios default --context="${CTX_CLUSTER2}"
 ----
 
 === Primary-Remote - Multi-Network
@@ -731,11 +743,10 @@ spec:
 EOF
 ----
 
-. Set the controlplane cluster and network for `cluster2`.
+. Set the controlplane cluster for `cluster2`.
 +
 ----
 kubectl --context="${CTX_CLUSTER2}" annotate namespace istio-system topology.istio.io/controlPlaneClusters=cluster1
-kubectl --context="${CTX_CLUSTER2}" label namespace istio-system topology.istio.io/network=network2
 ----
 
 . Install a remote secret on `cluster1` that provides access to the `cluster2` API server.