docs: Add comprehensive waypoint proxy update procedures

- Expand istio-ambient-update.md with detailed waypoint verification steps
- Add waypoint compatibility information for InPlace and RevisionBased strategies
- Include L7 feature verification procedures after control plane updates
- Add cross-namespace waypoint update considerations and troubleshooting
- Create dedicated 'Update' section in istio-ambient-waypoint.md
- Add 'L7 Feature Verification During Updates' subsection
- Add 'Cross-namespace Waypoint Updates' subsection
- Add comprehensive waypoint troubleshooting for update issues
- Update main README.md to include waypoint update documentation
- Include examples for HTTPRoute, AuthorizationPolicy, and telemetry verification

Signed-off-by: Rafael Zago <[email protected]>

Author: rafaelvzago

docs/README.md

@@ -67,6 +67,7 @@
 - [Introduction to Istio Waypoint Proxy](common/istio-ambient-waypoint.md#introduction-to-istio-waypoint-proxy)
   - [Core features](common/istio-ambient-waypoint.md#core-features)
   - [Getting Started](common/istio-ambient-waypoint.md#getting-started)
+  - [Update](common/istio-ambient-waypoint.md#update)
   - [Layer 7 Features in Ambient Mode](common/istio-ambient-waypoint.md#layer-7-features-in-ambient-mode)
   - [Troubleshoot issues](common/istio-ambient-waypoint.md#troubleshoot-issues)
   - [Cleanup](common/istio-ambient-waypoint.md#cleanup)

docs/common/istio-ambient-update.md

@@ -493,26 +493,12 @@ After updating all ambient components, verify that your ambient workloads are fu
 
 ```bash
 $ kubectl get pods -n bookinfo
-NAME                             READY   STATUS    RESTARTS   AGE
-details-v1-54ffdd5947-8gk5h      1/1     Running   0          7d
-productpage-v1-d49bb79b4-cb9sl   1/1     Running   0          7d
-ratings-v1-856f65bcff-h6kkf      1/1     Running   0          7d
-reviews-v1-848b8749df-wl5br      1/1     Running   0          7d
-reviews-v2-5fdf9886c7-8xprg      1/1     Running   0          7d
-reviews-v3-bb6b8ddc7-bvcm5       1/1     Running   0          7d
 ```
 
 2. Verify ZTunnel is processing traffic for your ambient workloads:
 
 ```bash
 $ istioctl ztunnel-config workloads --namespace ztunnel | grep bookinfo
-NAMESPACE    POD NAME                       ADDRESS      NODE                        WAYPOINT PROTOCOL
-bookinfo     details-v1-54ffdd5947-8gk5h    10.131.0.69  node1.example.com           None     HBONE
-bookinfo     productpage-v1-d49bb79b4-cb9sl 10.128.2.80  node2.example.com           None     HBONE
-bookinfo     ratings-v1-856f65bcff-h6kkf    10.131.0.70  node1.example.com           None     HBONE
-bookinfo     reviews-v1-848b8749df-wl5br    10.131.0.72  node1.example.com           None     HBONE
-bookinfo     reviews-v2-5fdf9886c7-8xprg    10.128.2.78  node2.example.com           None     HBONE
-bookinfo     reviews-v3-bb6b8ddc7-bvcm5     10.128.2.79  node2.example.com           None     HBONE
 ```
 
 3. Test connectivity within your mesh:
@@ -608,6 +594,31 @@ If you have deployed waypoint proxies for L7 features:
 * **Recreation:** In rare cases, you may need to recreate waypoint Gateway resources if there are breaking changes between versions.
 * **Verification:** Test L7 features after the upgrade to ensure waypoint proxies are functioning correctly. See [Layer 7 Features in Ambient Mode](./istio-ambient-waypoint.md#layer-7-features-in-ambient-mode) for testing examples.
 
+**Update Behavior by Strategy:**
+
+- **InPlace Strategy:** Waypoint proxies transition directly to the new control plane version
+- **RevisionBased Strategy:** Waypoint proxies function with both revisions during migration
+
+**L7 Feature Verification:**
+
+After upgrade, verify L7 features work correctly:
+
+```bash
+$ kubectl get authorizationpolicies -n bookinfo
+$ kubectl get httproutes -n bookinfo
+```
+
+**Cross-Namespace Waypoints:**
+
+Verify labels remain in place for cross-namespace waypoint usage:
+
+```bash
+$ kubectl get ns bookinfo --show-labels | grep waypoint
+bookinfo  Active  istio.io/use-waypoint-namespace=foo,istio.io/use-waypoint=waypoint-foo
+```
+
+For detailed waypoint update procedures, see [Updating Waypoint Proxies](./istio-ambient-waypoint.md#updating-waypoint-proxies).
+
 ### Impact on Existing Ambient Workloads
 
 During ambient mode upgrades:
@@ -653,8 +664,25 @@ bookinfo       Active   7d
 
 **Issue: Waypoint proxies not functioning**
 * Verify Gateway resource exists: `kubectl get gateway -n <namespace>`
+* Check Gateway programmed status: `kubectl get gateway -n <namespace> -o wide`
 * Check waypoint pod logs: `kubectl logs -n <namespace> -l gateway.networking.k8s.io/gateway-name=waypoint`
 * Ensure the namespace has the waypoint label: `istio.io/use-waypoint=<waypoint-name>`
+* For cross-namespace waypoints, verify both label pairs are present
+
+**Issue: L7 policies not enforced (authorization policies)**
+* Verify AuthorizationPolicy resources: `kubectl get authorizationpolicies -n <namespace>`
+* Check policy targets: `kubectl describe authorizationpolicy <name> -n <namespace>`
+* Verify waypoint pods are processing the policy: `kubectl logs -n <namespace> -l gateway.networking.k8s.io/gateway-name=waypoint | grep -i "policy"`
+
+**Issue: Traffic routing not working (HTTPRoute)**
+* Verify HTTPRoute resources: `kubectl get httproutes -n <namespace>`
+* Check route configuration: `kubectl describe httproute <name> -n <namespace>`
+* Test traffic distribution: `for i in {1..10}; do curl -s http://productpage:9080 | grep "reviews-v"; done`
+
+**Issue: Waypoint gateway not programmed**
+* Check waypoint deployment status: `kubectl get deployment -n <namespace> -l gateway.networking.k8s.io/gateway-name=waypoint`
+* Verify service exists: `kubectl get svc -n <namespace> | grep waypoint`
+* Check for Gateway API controller issues: `kubectl describe gateway <name> -n <namespace>`
 
 ---
 

docs/common/istio-ambient-waypoint.md

@@ -8,6 +8,10 @@
     - [Set up Istio Ambient Mode Resources and a Sample Application](#set-up-istio-ambient-mode-resources-and-a-sample-application)
     - [Deploy a Waypoint Proxy](#deploy-a-waypoint-proxy)
       - [Cross-namespace Waypoint](#cross-namespace-waypoint)
+  - [Update](#update)
+    - [Updating Waypoint Proxies](#updating-waypoint-proxies)
+    - [L7 Feature Verification During Updates](#l7-feature-verification-during-updates)
+    - [Cross-namespace Waypoint Updates](#cross-namespace-waypoint-updates)
   - [Layer 7 Features in Ambient Mode](#layer-7-features-in-ambient-mode)
     - [Traffic Routing](#traffic-routing)
     - [Security Authorization](#security-authorization)
@@ -113,6 +117,69 @@ kubectl label ns bookinfo istio.io/use-waypoint-namespace=foo
 kubectl label ns bookinfo istio.io/use-waypoint=waypoint-foo
 ```
 
+## Update
+
+This section covers updating waypoint proxies when upgrading Istio in ambient mode.
+
+### Updating Waypoint Proxies
+
+Waypoint proxies automatically work with control plane upgrades. Verify they function correctly:
+
+1. Check waypoint pod status:
+
+```bash
+$ kubectl get pods -n bookinfo -l gateway.networking.k8s.io/gateway-name=waypoint
+NAME                       READY   STATUS    RESTARTS   AGE
+waypoint-5d9c8b7f9-abc12   1/1     Running   0          5m
+```
+
+2. Verify Gateway is programmed:
+
+```bash
+$ kubectl get gateway -n bookinfo waypoint -o wide
+NAME       CLASS              ADDRESS        PROGRAMMED   AGE
+waypoint   istio-waypoint     10.96.123.45   True         7d
+```
+
+For detailed update procedures, see [Updating Waypoint Proxies](./istio-ambient-update.md#updating-waypoint-proxies-if-deployed).
+
+### L7 Feature Verification During Updates
+
+After control plane updates, verify L7 features work correctly:
+
+1. Test traffic routing:
+
+```bash
+$ kubectl exec "$(kubectl get pod -l app=reviews -n bookinfo -o jsonpath='{.items[0].metadata.name}')" -c reviews -n bookinfo -- curl -s http://productpage:9080/productpage | head -20
+```
+
+2. Verify authorization policies:
+
+```bash
+$ kubectl get authorizationpolicies -n bookinfo
+```
+
+3. Check waypoint logs for policy enforcement:
+
+```bash
+$ kubectl logs -n bookinfo -l gateway.networking.k8s.io/gateway-name=waypoint --tail=50
+```
+
+### Cross-namespace Waypoint Updates
+
+For cross-namespace waypoints, verify labels are in place after upgrades:
+
+```bash
+$ kubectl get ns bookinfo --show-labels
+bookinfo  Active  istio.io/dataplane-mode=ambient,istio.io/use-waypoint-namespace=foo,istio.io/use-waypoint=waypoint-foo
+```
+
+If cross-namespace waypoints stop working, re-apply the labels:
+
+```bash
+$ kubectl label ns bookinfo istio.io/use-waypoint-namespace=foo istio.io/use-waypoint=waypoint-foo --overwrite
+```
+
 ## Layer 7 Features in Ambient Mode
 
 The following section describes the stable features using Gateway API resource `HTTPRoute` and Istio resource `AuthorizationPolicy`. Other L7 features using a waypoint proxy will be discussed when they reach to Beta status.