From c706b31a3e4401c67e4219a4ce49a490212c2125 Mon Sep 17 00:00:00 2001 From: Francisco Herrera Date: Tue, 21 Oct 2025 18:41:21 +0200 Subject: [PATCH 1/8] Updating migration from sidecar to Ambient mode from review Adding some minors changes from review Signed-off-by: Francisco Herrera --- .../migration.adoc | 35 +++++++++---------- 1 file changed, 16 insertions(+), 19 deletions(-) diff --git a/docs/migrate-from-sidecar-to-ambient/migration.adoc b/docs/migrate-from-sidecar-to-ambient/migration.adoc index ec107d41a..806e17762 100644 --- a/docs/migrate-from-sidecar-to-ambient/migration.adoc +++ b/docs/migrate-from-sidecar-to-ambient/migration.adoc @@ -119,9 +119,9 @@ For Kubernetes: For Openshift: -- **Openshift 4.19+**: Minimum version for ambient mode support -- **Sail Operator v1.27+**: Must be running Sail Operator version 1.27 or later -- **Istio v1.27+**: Control plane must be v1.24 or later for ambient support +- **Openshift versions supported**: We support Openshift 4.14 and later but for versions older than 4.19 you will need to manually install Gateway API CRDs. +- **Sail Operator v1.27+**: Must be running Sail Operator version 1.27 or later. +- **Istio v1.27+**: Control plane must be v1.27 or later for ambient support on Openshift. - **Cluster Admin Access**: Required for namespace labeling and resource creation **Note**: for Openshift clusters, it's need the use of the local gateway mode for ambient deployments. Please refer to the Openshift documentation for more details: https://docs.redhat.com/en/documentation/red_hat_openshift_service_mesh/3.1/html/installing/ossm-istio-ambient-mode#ossm-installing-istio-ambient-mode_ossm-istio-ambient-mode. @@ -150,11 +150,13 @@ A critical architectural decision involves whether to deploy waypoint proxies. T **When Waypoints Are Used vs Not Used:** **Automatic Waypoint Activation occurs when:** + 1. **Namespace labeling**: Adding `istio.io/use-waypoint=` label to a namespace 2. **Service labeling**: Adding the label to specific services for granular control 3. **Pod labeling**: Adding the label to individual pods (requires `istio.io/waypoint-for: workload`) **Traffic Flow Decision Tree:** + - **Without waypoint labels**: Traffic flows directly through ztunnel (L4-only processing) - **With waypoint labels**: Traffic is intercepted and routed through waypoint proxies for L7 processing - **Mixed environments**: Some services use waypoints while others remain ztunnel-only @@ -185,8 +187,7 @@ For detailed waypoint configuration guidance, see link:../common/istio-ambient-w - Virtual Machine (VM) workload integration - SPIRE integration for identity federation -For additional compatibility considerations refer to: -- link:../common/coexistence.md [Sidecar-Ambient Coexistence Guidelines] +For additional compatibility considerations refer to: link:../common/coexistence.md[Sidecar-Ambient Coexistence Guidelines] [[pre-migration-checklist]] === 2.3 Pre-Migration Checklist @@ -206,13 +207,12 @@ NAME NAMESPACE PROFILE REVISIONS READY IN USE ACTIVE REVISION default istio-system 1 1 1 default Healthy v1.27.0 20m ---- -[source,console] ----- -# Verify no unsupported features are in use -kubectl get virtualservice,destinationrule -A ----- - -Note: if you have any of the unsupported features listed above, we will need to resolve those before proceeding with the migration. Take into account that ambient support PeerAuthentication but disable mode it's not supported, more information about this can be found here: https://istio.io/latest/docs/reference/config/security/peer_authentication/. +[NOTE] +==== +* If you have any of the unsupported features like VirtualServices or DestinationRules, during Step 5 you will need to migrate those to be compatible with ambient mode. +* Ambient supports PeerAuthentication, but disabled mode is not supported. More information: https://istio.io/latest/docs/reference/config/security/peer_authentication/ +* Migrate ingress gateways to use Gateway API resources before migration. More information: https://istio.io/latest/docs/reference/config/networking/gateway/ +==== **Application Namespace Validation:** @@ -277,7 +277,7 @@ Before starting migration, back up all existing Istio resources and namespace la [source,console] ---- # Backup all Istio resources -kubectl get istio,istiocni,virtualservice,destinationrule,authorizationpolicy,requestauthentication -A -o yaml > istio-backup.yaml +kubectl get istio,istiocni,virtualservice,destinationrule,authorizationpolicy,requestauthentication,httproute,gateway,peerauthentication -A -o yaml > istio-backup.yaml # Backup namespace labels kubectl get namespaces -o yaml > namespace-backup.yaml @@ -463,10 +463,10 @@ Existing sidecars need to support the HBONE protocol. Restart deployments in all # Restart workloads in each application namespace kubectl rollout restart deployment -n bookinfo -# Verify pods have restarted with ambient-aware sidecars +# Verify pods have restarted kubectl get pods -n bookinfo ---- -Note: during the restart, sidecars will be updated to support HBONE while still functioning as traditional sidecars. +Note: during the restart, sidecars will be updated to support HBONE while still functioning as traditional sidecars. Having HBONE support enabled is a prerequisite for ambient mode. [[step-32-validate-hbone-capability]] ==== Step 3.2 Validate HBONE Capability @@ -475,7 +475,7 @@ Check that sidecars now support HBONE protocol: [source,console] ---- -# Check for HBONE is enable in sidecar +# Check for HBONE is enabled in sidecar $ kubectl get pod $(kubectl get pods -n bookinfo -l app=ratings -o jsonpath='{.items[0].metadata.name}') -n bookinfo -o yaml | yq '.spec.containers[] | select(.name=="istio-proxy") | .env[] | select(.name=="PROXY_CONFIG")' name: PROXY_CONFIG value: | @@ -566,9 +566,6 @@ Apply the waypoint configurations: [source,console] ---- kubectl apply -f waypoint-bookinfo.yaml - -# Verify waypoints are created but not yet active -kubectl get gateway -n bookinfo ---- **Important**: Deploying a waypoint does not automatically make workloads use it. You must explicitly configure namespaces, services, or pods to use the waypoint. From 25c05465246add3e22cd0c89d79c6fd6c1b4ad8f Mon Sep 17 00:00:00 2001 From: Francisco Herrera Date: Tue, 21 Oct 2025 19:18:49 +0200 Subject: [PATCH 2/8] Update format Fix format in list Signed-off-by: Francisco Herrera --- docs/migrate-from-sidecar-to-ambient/migration.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/migrate-from-sidecar-to-ambient/migration.adoc b/docs/migrate-from-sidecar-to-ambient/migration.adoc index 806e17762..6efdade54 100644 --- a/docs/migrate-from-sidecar-to-ambient/migration.adoc +++ b/docs/migrate-from-sidecar-to-ambient/migration.adoc @@ -99,6 +99,7 @@ The migration from sidecar to ambient mode follows a structured, phased approach This migration guide uses example commands that can be adapted to any application. For reference purposes, we use placeholder values like ``, ``, and `` that you should replace with your actual application details. **Related Documentation:** + - If you want to follow along with a sample application, you can deploy the bookinfo application by following the steps described in link:../addons/addons.adoc#deploy-gateway-and-bookinfo[Deploying Gateway and Bookinfo] - For detailed waypoint proxy configuration, see link:../common/istio-ambient-waypoint.adoc[Waypoint Proxy Documentation] - For general application deployment guidance, refer to link:../common/install-bookinfo-app.adoc[Installing the Bookinfo Application] From 746b29b00e182d739a569f8ed1b325718a53b744 Mon Sep 17 00:00:00 2001 From: Francisco Herrera Date: Tue, 21 Oct 2025 19:42:32 +0200 Subject: [PATCH 3/8] Adding some more enchance from review Enchancements Signed-off-by: Francisco Herrera --- docs/migrate-from-sidecar-to-ambient/migration.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/migrate-from-sidecar-to-ambient/migration.adoc b/docs/migrate-from-sidecar-to-ambient/migration.adoc index 6efdade54..fd42efb8e 100644 --- a/docs/migrate-from-sidecar-to-ambient/migration.adoc +++ b/docs/migrate-from-sidecar-to-ambient/migration.adoc @@ -300,7 +300,7 @@ This migration follows a structured step-by-step approach, with each step includ [[step-1-prerequisites-validation]] === Step 1: Prerequisites Validation -Before starting migration, validate your cluster meets all requirements +Before starting migration, validate your cluster meets all requirements and check the current configuration for compatibility. **Enhanced Policy Compatibility Check:** [source,console] @@ -329,7 +329,7 @@ echo "=== Authorization policies requiring waypoint deployment ===" kubectl get authorizationpolicy -A -o yaml | grep -c -E "(methods|paths|headers)" ---- -Note: You will need to resolve any unsupported features before proceeding. This includes: +Note: In the step 5 of this guide you will need to migrate unsupported features. This includes: - Converting VirtualServices and DestinationRules to HTTPRoute and Gateway resources - Creating granular services to replace subset-based routing From 939015e2ac245718303c3ec1c298ed85ac6b469c Mon Sep 17 00:00:00 2001 From: Francisco Herrera Date: Tue, 21 Oct 2025 19:45:43 +0200 Subject: [PATCH 4/8] Fix list format Fix list format Signed-off-by: Francisco Herrera --- docs/migrate-from-sidecar-to-ambient/migration.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/migrate-from-sidecar-to-ambient/migration.adoc b/docs/migrate-from-sidecar-to-ambient/migration.adoc index fd42efb8e..e2e49600a 100644 --- a/docs/migrate-from-sidecar-to-ambient/migration.adoc +++ b/docs/migrate-from-sidecar-to-ambient/migration.adoc @@ -597,6 +597,7 @@ Ambient mode uses the Kubernetes Gateway API instead of Istio's VirtualService a - **DestinationRule subsets** to **Version-specific Services**: Since Gateway API doesn't support subset-based routing For comprehensive conversion guidance, refer to: + - https://istio.io/latest/docs/reference/config/networking/virtual-service/[Istio VirtualService] - https://gateway-api.sigs.k8s.io/guides/http-routing/[Gateway API HTTPRoute Documentation] From 7280e18f3a209021129c30c8e4ce886c6534a04f Mon Sep 17 00:00:00 2001 From: Francisco Herrera Date: Tue, 21 Oct 2025 19:47:37 +0200 Subject: [PATCH 5/8] Fix list format Fix list format Signed-off-by: Francisco Herrera --- docs/migrate-from-sidecar-to-ambient/migration.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/migrate-from-sidecar-to-ambient/migration.adoc b/docs/migrate-from-sidecar-to-ambient/migration.adoc index e2e49600a..993409ef3 100644 --- a/docs/migrate-from-sidecar-to-ambient/migration.adoc +++ b/docs/migrate-from-sidecar-to-ambient/migration.adoc @@ -1155,6 +1155,7 @@ After migration, use Kiali to visualize the service mesh. You should see traffic === 5.1 Common Issues For comprehensive troubleshooting guidance, refer to: + - https://istio.io/latest/docs/ambient/usage/troubleshoot-waypoint/[Istio Ambient Troubleshooting Documentation] - https://istio.io/latest/docs/ops/diagnostic-tools/[Istio Diagnostic Tools] From 6204b95d8b59228a4d47120c8ddcf96b1dfde039 Mon Sep 17 00:00:00 2001 From: Francisco Herrera Date: Tue, 21 Oct 2025 19:48:42 +0200 Subject: [PATCH 6/8] Fix list format Fix list format Signed-off-by: Francisco Herrera --- docs/migrate-from-sidecar-to-ambient/migration.adoc | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/migrate-from-sidecar-to-ambient/migration.adoc b/docs/migrate-from-sidecar-to-ambient/migration.adoc index 993409ef3..e550d51b1 100644 --- a/docs/migrate-from-sidecar-to-ambient/migration.adoc +++ b/docs/migrate-from-sidecar-to-ambient/migration.adoc @@ -1473,16 +1473,19 @@ curl -s http://$GATEWAY_URL/ ==== When to Use Each Rollback Option **Use Step-Specific Rollbacks when:** + - Single step validation fails - Issues are isolated to specific components - Other migration steps are working correctly **Use Sidecar Restoration when:** + - Service connectivity is disrupted - L7 policies are not enforcing correctly - Need immediate service restoration **Prevention Best Practices:** + - Always create backups before starting migration - Test rollback procedures in non-production environments - Monitor service health continuously during migration From 0d977a6d899df026760baa6b59e1cca092fe2657 Mon Sep 17 00:00:00 2001 From: Francisco Herrera Date: Tue, 21 Oct 2025 19:59:36 +0200 Subject: [PATCH 7/8] Update docs/migrate-from-sidecar-to-ambient/migration.adoc Co-authored-by: Matej Kralik Signed-off-by: Francisco Herrera --- docs/migrate-from-sidecar-to-ambient/migration.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrate-from-sidecar-to-ambient/migration.adoc b/docs/migrate-from-sidecar-to-ambient/migration.adoc index e550d51b1..37308dd5a 100644 --- a/docs/migrate-from-sidecar-to-ambient/migration.adoc +++ b/docs/migrate-from-sidecar-to-ambient/migration.adoc @@ -188,7 +188,7 @@ For detailed waypoint configuration guidance, see link:../common/istio-ambient-w - Virtual Machine (VM) workload integration - SPIRE integration for identity federation -For additional compatibility considerations refer to: link:../common/coexistence.md[Sidecar-Ambient Coexistence Guidelines] +For additional compatibility considerations refer to: link:../common/coexistence.adoc[Sidecar-Ambient Coexistence Guidelines] [[pre-migration-checklist]] === 2.3 Pre-Migration Checklist From 4599a610b7a83b9d8c5f045a5184d3ddadbb578d Mon Sep 17 00:00:00 2001 From: Francisco Herrera Date: Tue, 21 Oct 2025 20:38:10 +0200 Subject: [PATCH 8/8] Update from review Adding message for labeling namespaces Signed-off-by: Francisco Herrera --- docs/migrate-from-sidecar-to-ambient/migration.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrate-from-sidecar-to-ambient/migration.adoc b/docs/migrate-from-sidecar-to-ambient/migration.adoc index 37308dd5a..3e9c11fc1 100644 --- a/docs/migrate-from-sidecar-to-ambient/migration.adoc +++ b/docs/migrate-from-sidecar-to-ambient/migration.adoc @@ -220,7 +220,7 @@ default istio-system 1 1 1 default [source,console] ---- # Check your application namespaces for sidecar injection -kubectl get namespaces -l istio.io/rev=default +kubectl get namespaces -l istio.io/rev=default #or any other istio revision name. Also, check if you are using instead istio-injection=enabled label. NAME STATUS AGE bookinfo Active 6m56 ----