Clarify gateway canary upgrade (#12570)

* Clarify gateway canary upgrade

Signed-off-by: Faseela K <faseela.k@est.tech>

* Apply suggestions from code review

Co-authored-by: Eric Van Norman <ericvn@us.ibm.com>

* Update index.md

---------

Signed-off-by: Faseela K <faseela.k@est.tech>
Co-authored-by: Eric Van Norman <ericvn@us.ibm.com>

content/en/docs/setup/upgrade/canary/index.md

@@ -76,8 +76,8 @@ istio-sidecar-injector-canary   2          114s
 
 ## Data plane
 
-Unlike istiod, Istio gateways do not run revision-specific instances, but are instead in-place upgraded to use the new control plane revision.
+Refer to [Gateway Canary Upgrade](/docs/setup/additional-setup/gateway/#canary-upgrade-advanced) to understand how to run revision specific instances of Istio gateway.
-You can verify that the `istio-ingress` gateway is using the `canary` revision by running the following command:
+In this example, since we use the `default` Istio profile, Istio gateways do not run revision-specific instances, but are instead in-place upgraded to use the new control plane revision. You can verify that the `istio-ingress` gateway is using the `canary` revision by running the following command:
 
 {{< text bash >}}
 $ istioctl proxy-status | grep "$(kubectl -n istio-system get pod -l app=istio-ingressgateway -o jsonpath='{.items..metadata.name}')" | awk '{print $10}'

content/en/docs/setup/upgrade/helm/canaryupgrade_test.sh

@@ -33,8 +33,8 @@ _verify_lines snip_canary_upgrade_recommended_3 "
 + canary
 "
 
-snip_canary_upgrade_recommended_4
+snip_canary_upgrade_recommended_6
-_rewrite_helm_repo snip_canary_upgrade_recommended_5
+_rewrite_helm_repo snip_canary_upgrade_recommended_7
 
 _rewrite_helm_repo helm template istiod istio/istiod -s templates/revision-tags.yaml --set revisionTags="{prod-stable}" --set revision=1-9-5 -n istio-system | kubectl delete -f -
 _rewrite_helm_repo helm template istiod istio/istiod -s templates/revision-tags.yaml --set revisionTags="{prod-canary}" --set revision=1-10-0 -n istio-system | kubectl delete -f -

content/en/docs/setup/upgrade/helm/index.md

@@ -66,7 +66,26 @@ primary and canary installations.
       istiod-canary-9cc9fd96f-jpc7n   1/1     Running   0          34m   canary
     {{< /text >}}
 
-1. Follow the steps [here](/docs/setup/upgrade/canary/) to test or migrate
+1. If you are using [Istio gateways](/docs/setup/additional-setup/gateway/#deploying-a-gateway), install a canary revision of the Gateway chart by setting the revision value:
+
+    {{< text bash >}}
+    $ helm install istio-ingress-canary istio/gateway \
+        --set revision=canary \
+        -n istio-ingress
+    {{< /text >}}
+
+1. Verify that you have two versions of `istio-ingress gateway` installed in your cluster:
+
+    {{< text bash >}}
+    $ kubectl get pods -L istio.io/rev -n istio-ingress
+      NAME                                    READY   STATUS    RESTARTS   AGE     REV
+      istio-ingress-754f55f7f6-6zg8n          1/1     Running   0          5m22s   default
+      istio-ingress-canary-5d649bd644-4m8lp   1/1     Running   0          3m24s   canary
+    {{< /text >}}
+
+    See [Upgarding Gateways](/docs/setup/additional-setup/gateway/#canary-upgrade-advanced) for in-depth documentation on gateway canary upgrade.
+
+1. Follow the steps [here](/docs/setup/upgrade/canary/#data-plane) to test or migrate
    existing workloads to use the canary control plane.
 
 1. Once you have verified and migrated your workloads to use the canary control

content/en/docs/setup/upgrade/helm/snips.sh

@@ -53,10 +53,26 @@ kubectl get pods -l app=istiod -L istio.io/rev -n istio-system
 ENDSNIP
 
 snip_canary_upgrade_recommended_4() {
-helm delete istiod -n istio-system
+helm install istio-ingress-canary istio/gateway \
+    --set revision=canary \
+    -n istio-ingress
 }
 
 snip_canary_upgrade_recommended_5() {
+kubectl get pods -L istio.io/rev -n istio-ingress
+}
+
+! read -r -d '' snip_canary_upgrade_recommended_5_out <<\ENDSNIP
+  NAME                                    READY   STATUS    RESTARTS   AGE     REV
+  istio-ingress-754f55f7f6-6zg8n          1/1     Running   0          5m22s   default
+  istio-ingress-canary-5d649bd644-4m8lp   1/1     Running   0          3m24s   canary
+ENDSNIP
+
+snip_canary_upgrade_recommended_6() {
+helm delete istiod -n istio-system
+}
+
+snip_canary_upgrade_recommended_7() {
 helm upgrade istio-base istio/base --set defaultRevision=canary -n istio-system --skip-crds
 }