docs: Add comprehensive Istio Ambient Mode update and waypoint proxy procedures #1279
+956
−25
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Collaborator
|
Hi @rafaelvzago. Thanks for your PR. I'm waiting for a istio-ecosystem or istio member to verify that this patch is reasonable to test. If it is, they should reply with Once the patch is verified, the new status will be reflected by the I understand the commands that are listed here. Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
Contributor
Author
|
Hi maintainers, I notice the PR has a rebase conflict due to format differences - the upstream repository uses AsciiDoc (.adoc) format while this PR uses Markdown (.md) format. I have two options to resolve this:
Which approach would be preferred? I'm ready to convert if needed - it will be a straightforward format conversion without any content changes. The documentation content itself is comprehensive and follows the project's contributor guidelines, so it's purely a format matter. |
rafaelvzago
force-pushed
the
ambient-mode-update
branch
from
57ce9d8 to
d5838f9
Compare
Contributor
Author
|
Update: I've proactively converted all documentation to AsciiDoc format to align with the upstream repository standards and resolve the rebase conflict. What Changed: ✅ All documentation files are now in AsciiDoc format (.adoc):
Branch Updated:
Ready for Merge: Commit: d5838f9 - docs: Add comprehensive Istio Ambient Mode update and waypoint procedures in AsciiDoc |
rafaelvzago
force-pushed
the
ambient-mode-update
branch
from
d5838f9 to
e848f21
Compare
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1279 +/- ##
==========================================
+ Coverage 77.52% 78.91% +1.39%
==========================================
Files 44 44
Lines 2834 2253 -581
==========================================
- Hits 2197 1778 -419
+ Misses 528 368 -160
+ Partials 109 107 -2 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Contributor
|
/ok-to-test |
fjglira
reviewed
Oct 17, 2025
Contributor
Hi, in upstream documentation, we should keep all the doc files in ASCII format. Please also take into account that in order to have a proper automation docs test, we should keep the format in all the code blocks and also mark the code blocks with the proper tag. For example, for the update strategy with a sidecar, we have 3 test cases: |
…e docs Addressed documentation duplication by making update-strategy.adoc the single source of truth for strategy concepts while keeping istio-ambient-update.adoc focused on ambient-specific procedures. Changes to docs/update-strategy/update-strategy.adoc: - Added new 'Understanding Versioning' section explaining semantic versioning (X.Y.Z format with major/minor/patch definitions) - Added note clarifying that InPlace and RevisionBased strategies apply to both sidecar and ambient modes - Added cross-reference to istio-ambient-update.adoc for ambient-specific update procedures - Updated table of contents to include new versioning section Changes to docs/common/istio-ambient-update.adoc: - Replaced full 'Understanding versioning' section with reference to update-strategy.adoc#understanding-versioning - Replaced 'About Istio update process' section with streamlined 'Selecting an Update Strategy' section that references the general strategy doc - Refactored 'About InPlace strategy' to 'Updating with InPlace Strategy' with reference to general strategy doc + ambient-specific considerations - Refactored 'About RevisionBased strategy' to 'Updating with RevisionBased Strategy' with reference to general strategy doc + ambient-specific considerations - Enhanced intro section to highlight key ambient mode differences upfront - Kept all unique ambient content: IstioCNI, ZTunnel, Waypoint proxy updates, special considerations, and troubleshooting Changes to docs/README.adoc: - Updated anchor links for ambient update doc sections: - #about-inplace-strategy → #updating-with-inplace-strategy - #about-revisionbased-strategy → #updating-with-revisionbased-strategy Result: Both documents remain, no duplication, clear separation of concerns, and bidirectional cross-references for better navigation. Signed-off-by: Rafael Zago <[email protected]>
Streamlined the Layer 7 features verification section by removing redundant resource listing steps: - Removed 'Check HTTPRoute resources' step before testing traffic distribution (users can directly test traffic instead of listing resources first) - Removed 'Check AuthorizationPolicy resources' step before testing policy enforcement (users can directly test enforcement instead of listing first) These changes make the verification process more direct and actionable by focusing on actual testing rather than resource inspection. Users who need to inspect resources can still use kubectl get commands independently. Also added newline at end of file. Signed-off-by: Rafael Zago <[email protected]>
Add proper test tags (subs="attributes+" and name attributes) to code blocks in ambient mode documentation files to enable automated documentation testing, following the pattern established in update-strategy.adoc. Changes to docs/common/istio-ambient-update.adoc: - Added test tags for InPlace strategy: ambient-inplace-update-strategy - Added test tags for RevisionBased strategy: ambient-revision-based-strategy - Added test tags for rollback procedure: ambient-revision-rollback - Added test tags for IstioCNI update: ambient-update-istiocni - Added test tags for ZTunnel update: ambient-update-ztunnel - Added test tags for workload verification: ambient-verify-workloads - Added test tags for waypoint update: ambient-update-waypoint Changes to docs/common/istio-ambient-waypoint.adoc: - Added test tags for prerequisites: ambient-waypoint-prerequisites - Added test tags for waypoint deployment: ambient-waypoint-deploy - Added test tags for cross-namespace deployment: ambient-waypoint-crossns-deploy - Added test tags for InPlace updates: ambient-waypoint-update-inplace - Added test tags for RevisionBased updates: ambient-waypoint-update-revisionbased - Added test tags for L7 verification: ambient-waypoint-verify-l7 - Added test tags for cross-namespace updates: ambient-waypoint-crossns-update - Added test tags for L7 features: ambient-waypoint-l7-features - Added test tags for cleanup: ambient-waypoint-cleanup Addresses PR feedback from istio-ecosystem#1279 requesting proper automation test tags for upstream documentation. Signed-off-by: Rafael Zago <[email protected]>
Merged the "About the Istio CNI update process" section into the "Updating IstioCNI" section to eliminate duplication and improve documentation flow. Changes: - Enhanced "Updating IstioCNI" section with conceptual explanation of in-place updates and daemonset behavior - Added spec.version field documentation and format guidance - Included notes about RevisionBased compatibility - Removed duplicate "About the Istio CNI update process" section - All procedural content preserved Addresses reviewer feedback from PR istio-ecosystem#1279 to club duplicate sections into a single comprehensive IstioCNI update guide. Signed-off-by: Rafael Zago <[email protected]>
… update instructions - Streamlined control plane update steps by combining redundant verification steps - Removed separate monitoring and pod status checks (steps 2, 5, 6) - Consolidated verification into a single step with optional log checking - Added inline summary for IstioCNI and ZTunnel updates for completeness - Maintained reference to detailed procedures in Common Update Procedures section Addresses feedback to reduce redundant steps while providing complete upgrade instructions for all ambient components in the InPlace strategy. Signed-off-by: Rafael Zago <[email protected]>
Signed-off-by: Rafael Zago <[email protected]>
… versions Signed-off-by: Rafael Zago <[email protected]>
Eliminate duplication between README.adoc, update-strategy.adoc, and istio-ambient-update.adoc while preserving all doc tests and ambient-specific content. Changes: - Simplified README.adoc ambient update section to single link - Enhanced update-strategy.adoc with prominent ambient mode note - Streamlined istio-ambient-update.adoc to reference main update strategy docs for InPlace/RevisionBased explanations - Preserved all 44 ambient-specific doc test markers - Kept detailed ambient-specific procedures (IstioCNI, ZTunnel, Waypoint) The documentation now follows a cleaner structure with minimal duplication while maintaining comprehensive ambient mode guidance. Signed-off-by: Rafael Zago <[email protected]>
Update documentation to accurately reflect that RevisionBased update strategy has significant limitations when used with Istio ambient mode: - Only one ztunnel instance can run cluster-wide at any time - Manual CRD synchronization required between Istio and ZTunnel revisions - Ztunnel must be manually reconfigured to point to appropriate control plane Changes made: - Add prominent warnings in both istio-ambient-mode.adoc and istio-ambient-update.adoc recommending InPlace strategy for ambient mode - Correct misleading statements suggesting ztunnel can communicate with multiple control plane versions simultaneously - Add detailed explanation of limitations in RevisionBased strategy section - Update strategy selection guidance to clearly indicate InPlace as recommended approach for ambient deployments This addresses feedback that the previous documentation incorrectly suggested RevisionBased updates work seamlessly with ambient mode. Signed-off-by: Rafael Zago <[email protected]>
Update the ambient mode upgrade documentation to accurately reflect that running multiple replicas of istiod helps minimize but does not completely eliminate the possibility of brief traffic disruption during InPlace control plane upgrades. Changes: - Updated InPlace strategy section to clarify that HA mode minimizes but doesn't eliminate downtime risk - Added reference to upstream Istio ambient upgrade documentation - Updated tip and recommendations sections with accurate HA limitations This addresses feedback from contributor review pointing to upstream Istio documentation that confirms even with multiple replicas, some brief downtime may still occur during ambient mode upgrades. Signed-off-by: Rafael Zago <[email protected]>
Add list continuation markers (+) before code blocks within numbered lists to prevent list numbering from restarting at 1 after each code block. Fixed sections: - InPlace Strategy: Added 2 continuation markers - RevisionBased Strategy: Added 3 continuation markers - Cross-namespace Waypoint Updates: Added 2 continuation markers This ensures numbered lists render correctly with sequential numbering (1, 2, 3) instead of (1, 1, 1). Signed-off-by: Rafael Zago <[email protected]>
Add blank line after bold text to ensure proper rendering of bullet list in the Troubleshooting Common Issues section. Signed-off-by: Rafael Zago <[email protected]>
Add a NOTE to the 'Verifying Ambient Workloads' section explaining that the examples use the bookinfo sample application and that users should adapt the steps to their own applications. Signed-off-by: Rafael Zago <[email protected]>
- Add new 'Updating Components' section to README.md with detailed IstioCNI update procedures - Replace detailed content in istio-ambient-update.adoc with reference link to README - Update internal references throughout ambient update documentation This improves discoverability of the IstioCNI update procedure by placing it in the main README while maintaining proper cross-references in the detailed ambient mode documentation. Signed-off-by: Rafael Zago <[email protected]>
Replace hardcoded 'bookinfo' namespace with '<NAMESPACE>' placeholder in kubectl rollout commands to make the documentation more reusable and clearly indicate to users that they should substitute their own namespace. Changes: - kubectl rollout restart deployment -n <NAMESPACE> - kubectl rollout status deployment -n <NAMESPACE> This aligns with the existing note that bookinfo is just an example. Signed-off-by: Rafael Zago <[email protected]>
Add clarification in the RevisionBased strategy section about recommended version compatibility between waypoint proxies and control plane. Documents that waypoint proxies should be kept within one minor version (n or n-1) of the control plane, following Istio's general support policy. This addresses questions about version compatibility recommendations similar to those provided for CNI components. Signed-off-by: Rafael Zago <[email protected]>
Replace plain text reference with proper AsciiDoc cross-reference link to the 'Updating Waypoint Proxies (If Deployed)' section in the ambient mode update documentation. Signed-off-by: Rafael Zago <[email protected]>
…ification Add real-world example output to kubectl logs commands in the ambient waypoint documentation to help users understand what they should expect to see when verifying their waypoint proxy is properly connected to the control plane. Examples show: - InPlace strategy: Connection to standard istiod service - RevisionBased strategy: Connection to revision-specific istiod service This addresses the contributor feedback requesting example output for better user guidance. Signed-off-by: Rafael Zago <[email protected]>
…rification Update waypoint proxy verification steps to use istioctl proxy-status instead of kubectl logs for more reliable connection verification. Changes: - Replace log-based verification with istioctl proxy-status command - Add example outputs showing correct column format - Provide explanations of output fields (CDS, LDS, EDS, RDS, ISTIOD, VERSION) - Update both InPlace and RevisionBased strategy sections The istioctl proxy-status command queries the control plane directly, providing accurate synchronization status and connected istiod information. Addresses PR feedback requesting more reliable verification method and example outputs to help users understand expected results. Signed-off-by: Rafael Zago <[email protected]>
Improve the L7 Feature Verification section for traffic routing by: - Adding reference to the existing Traffic Routing section example - Providing detailed explanation of the test command - Including sample output showing expected traffic distribution (90/10 split) - Adding interpretive guidance to help users understand results This addresses contributor feedback requesting more context and expected outputs for HTTPRoute traffic distribution testing. Signed-off-by: rzago Signed-off-by: Rafael Zago <[email protected]>
Add comprehensive context and test cases for verifying L7 authorization policies enforced by waypoint proxies. This enhancement addresses contributor feedback requesting better examples and clearer expectations. Changes: - Add introductory context explaining the productpage-waypoint policy - Include test case for denied access (ratings service) - Add test case for allowed access (curl service) - Provide expected outputs for both scenarios - Explain why each test succeeds or fails This helps users verify that waypoint proxies correctly enforce L7 authorization rules during and after updates. Signed-off-by: Rafael Zago <[email protected]>
- Mark step 3 as optional to indicate manual updates are not always required - Add Option A (Recommended): restart waypoint pods using kubectl rollout restart - Keep existing patch command as Option B for explicit version pinning - Document that waypoint proxies automatically use correct proxy version when reconnecting to new control plane revision - Add NOTE explaining when manual image patching is actually necessary - Addresses feedback about automatic update behavior and restart alternative This clarifies the confusion around when manual waypoint proxy updates are needed versus the automatic behavior during RevisionBased control plane updates. Signed-off-by: Rafael Zago <[email protected]>
Remove the recommendation about using node cordoning and blue/green node pools from the ambient mode upgrade documentation until a proper solution is identified. Signed-off-by: Rafael Zago <[email protected]>
…ts, add IstioCNI/ZTunnel prereqs - Rephrase "Manual CRD Synchronization" to "Manual Configuration Synchronization" (revision name sync between Istio and ZTunnel resources) - Remove restart rollout/status steps not needed in ambient - Add IstioCNI and ZTunnel prereqs for InPlace and RevisionBased sections Signed-off-by: Rafael Zago <[email protected]>
rafaelvzago
force-pushed
the
ambient-mode-update
branch
from
35ec7b8 to
1287b0d
Compare
Contributor
Author
dgn
reviewed
Nov 8, 2025
| istio-cni-node-ghi56 1/1 Running 0 3m | ||
| ``` | ||
|
|
||
| **Note:** When using the RevisionBased strategy, IstioCNI is compatible with multiple control plane versions and continues to work with both the old and new control planes during the workload migration. |
Collaborator
There was a problem hiding this comment.
maybe we should add that generally, [n-1..n+1] versions are supported
| + | ||
| [source,bash,subs="attributes+",name="ambient-waypoint-update-revisionbased"] | ||
| ---- | ||
| $ kubectl patch gateway waypoint -n bookinfo --type='merge' -p '{"spec":{"template":{"spec":{"containers":[{"name":"istio-proxy","image":"docker.io/istio/proxyv2:1.26.4"}]}}}}' |
Collaborator
There was a problem hiding this comment.
this doesn't look right. did you mean patching the deployment?
| $ kubectl patch gateway waypoint -n bookinfo --type='merge' -p '{"spec":{"template":{"spec":{"containers":[{"name":"istio-proxy","image":"docker.io/istio/proxyv2:1.26.4"}]}}}}' | ||
| ---- | ||
| + | ||
| NOTE: Manually setting the proxy image version is only necessary when you want to pin to a specific version different from what the control plane would automatically provide, or in scenarios where automatic updates do not occur due to environmental or configuration constraints. In standard RevisionBased updates, Option A (restart) is sufficient. |
Collaborator
There was a problem hiding this comment.
afaik neither restart nor manual version updates should be necessary. istiod will reconcile the deployment after it has been updated, and update the waypoint
| - <<example-using-the-revisionbased-strategy-and-an-istiorevisiontag>> | ||
|
|
||
| [[understanding-versioning]] | ||
| == Understanding Versioning |
Collaborator
There was a problem hiding this comment.
not sure why we need this new section, and especially as part of this PR. apart from that, we really just follow istio versions, except in the patch version
Collaborator
|
this has a bit too much of an AI sound to it for me |
Contributor
fjglira
reviewed
Nov 8, 2025
Contributor
fjglira
left a comment
fjglira
left a comment
There was a problem hiding this comment.
You can mode doc automation to a consecutive PR, but please create an issue to track this and avoid forgetting. I leave you a comment with an example on what is needed and more information is here: https://github.com/openshift-service-mesh/sail-operator/blob/main/docs/guidelines/guidelines.adoc#automated-testing-over-the-documentation
| Waypoint proxies are deployed using Kubernetes Gateway resources. As of Kubernetes 1.30 and OpenShift 4.17, the Kubernetes Gateway API CRDs are not available by default and must be installed to be used. This can be done with the following command: | ||
|
|
||
| [source,bash,subs="attributes+"] | ||
| [source,bash,subs="attributes+",name="ambient-waypoint-prerequisites"] |
Contributor
There was a problem hiding this comment.
To be able to get any doc test executed, you will need to add ifdef validation steps into the documentation, adding just the attribute name if will not ensure that test are going to be executed. Currently this files are not being executed:
reating TEST_DIR directory: /logs/artifacts/docs.test
Tests list: /home/prow/go/src/github.com/istio-ecosystem/sail-operator/docs/README.adoc:cni-update-test /home/prow/go/src/github.com/istio-ecosystem/sail-operator/docs/deployment-models/multiple-mesh.adoc:multiple-meshes /home/prow/go/src/github.com/istio-ecosystem/sail-operator/docs/dual-stack/dual-stack.adoc:dual-stack /home/prow/go/src/github.com/istio-ecosystem/sail-operator/docs/general/istiod-ha.adoc:istio-ha-autoscaling /home/prow/go/src/github.com/istio-ecosystem/sail-operator/docs/general/istiod-ha.adoc:istio-ha-replicacount /home/prow/go/src/github.com/istio-ecosystem/sail-operator/docs/update-strategy/update-strategy.adoc:inplace-update-strategy /home/prow/go/src/github.com/istio-ecosystem/sail-operator/docs/update-strategy/update-strategy.adoc:revision-based-strategy /home/prow/go/src/github.com/istio-ecosystem/sail-operator/docs/update-strategy/update-strategy.adoc:revision-istiorevisiontag-strategy
Creating test file: /logs/artifacts/docs.test/cni-update-test.sh
Please take as example https://github.com/openshift-service-mesh/sail-operator/blob/12e0d3c9f5affc76920c54ad26a66c726bcdc1ca/docs/general/istiod-ha.adoc?plain=1#L60. If you prefer this can be added in a consecutive PR, but it will be great to have those test being added. Think that to be able to execute the test you will need to add a setup code block hidden using the ifdef hidden block
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
6 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What type of PR is this?
What this PR does / why we need it:
This PR adds comprehensive documentation for updating Istio when deployed in ambient mode using the Sail Operator, including detailed waypoint proxy update procedures.
Content Added:
New File:
docs/common/istio-ambient-update.md(695 lines)Updated File:
docs/common/istio-ambient-waypoint.md(291 lines)Updated File:
docs/README.mdWhy This Is Needed:
Ambient mode is a Technology Preview feature that requires different update procedures compared to traditional sidecar mode. This documentation:
Based on content from PR #549 in the OpenShift Service Mesh fork, adapted for upstream Sail Operator.
Which issue(s) this PR fixes:
Related PR: openshift-service-mesh#549
Additional information:
Documentation Quality:
Statistics:
Notes: