ambient: add traffic routing docs #12781
Merged
Conversation
This file contains 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
This fills in part of the architecture doc for ambient. Note this is intentionally low-level. This attempts to mirror https://istio.io/latest/docs/ops/configuration/traffic-management/traffic-routing/ but for ambient.
istio-testing
added
the
size/M
frankbu
reviewed
Feb 24, 2023
frankbu
reviewed
Feb 24, 2023
| @@ -13,4 +13,77 @@ This page is under construction. | |||
|
|
|||
| ## Traffic routing | |||
|
|
|||
| In ambient mode, workloads can fall into 3 categories: | |||
| * Uncaptured: this is a standard pod without any mesh features enabled | |||
| * Captured: this is a pod that has traffic intercepted by `ztunnel`. Pods can be captured by setting the `istio.io/dataplane-mode=ambient` label on a namespace. | |||
There was a problem hiding this comment.
I assume there will be some intro material that describes the architectural components, but I wonder if it might be worth adding some glossary entries and reference them in the first use in this doc, to make it more easy to read alone?
Suggested change
| * Captured: this is a pod that has traffic intercepted by `ztunnel`. Pods can be captured by setting the `istio.io/dataplane-mode=ambient` label on a namespace. | |
| * Captured: this is a pod that has traffic intercepted by {{< gloss >}}ztunnel{{< /gloss >}}. Pods can be captured by setting the `istio.io/dataplane-mode=ambient` label on a namespace. |
There was a problem hiding this comment.
Yes this is intended to be the deep dive. Writing the docs in reverse order, but users will see this last. Agree on glossary
There was a problem hiding this comment.
Ill make another PR with glossary
frankbu
reviewed
Feb 24, 2023
| In ambient mode, workloads can fall into 3 categories: | ||
| * Uncaptured: this is a standard pod without any mesh features enabled | ||
| * Captured: this is a pod that has traffic intercepted by `ztunnel`. Pods can be captured by setting the `istio.io/dataplane-mode=ambient` label on a namespace. | ||
| * Waypoint enabled: this is a pod that is "Captured" *and* has a waypoint proxy deployed. |
There was a problem hiding this comment.
Suggested change
| * Waypoint enabled: this is a pod that is "Captured" *and* has a waypoint proxy deployed. | |
| * Waypoint enabled: this is a pod that is "Captured" *and* has a {{< gloss >}}waypoint proxy{{< /gloss >}} deployed. |
There was a problem hiding this comment.
Noting the next line just uses waypoint, would it be better to have the single word in the glossary?
frankbu
reviewed
Feb 24, 2023
frankbu
reviewed
Feb 24, 2023
| Requests to a `Service` will be sent to an endpoint within the `Service`, and requests directly to a `Pod` IP would be go directly to that `Pod` IP. | ||
|
|
||
| However, depending on the destination's capabilities, different behavior will occur. | ||
| If the destination is also captured, or otherwise has Istio proxy capabilities (such as a sidecar), the request will be upgraded to an encrypted HBONE tunnel. |
There was a problem hiding this comment.
Suggested change
| If the destination is also captured, or otherwise has Istio proxy capabilities (such as a sidecar), the request will be upgraded to an encrypted HBONE tunnel. | |
| If the destination is also captured, or otherwise has Istio proxy capabilities (such as a sidecar), the request will be upgraded to an encrypted {{< gloss >}}HBONE{{< /gloss >}} tunnel. |
frankbu
reviewed
Feb 24, 2023
frankbu
reviewed
Feb 24, 2023
frankbu
reviewed
Feb 24, 2023
frankbu
reviewed
Feb 24, 2023
frankbu
reviewed
Feb 24, 2023
|
|
||
| When the destination is waypoint enabled, all requests *must* go through the waypoint, where policy is enforced. | ||
| The `ztunnel` will enforce this occurs. | ||
| However, there is an edge case: a well behaving HBONE client (such as another ztunnel or Istio sidecar) would know to send to the waypoint, but for other clients |
There was a problem hiding this comment.
Suggested change
| However, there is an edge case: a well behaving HBONE client (such as another ztunnel or Istio sidecar) would know to send to the waypoint, but for other clients | |
| However, there is an edge case: a well behaving HBONE client (such as another `ztunnel` or Istio sidecar) would know to send to the waypoint, but other clients |
frankbu
reviewed
Feb 24, 2023
| The `ztunnel` will enforce this occurs. | ||
| However, there is an edge case: a well behaving HBONE client (such as another ztunnel or Istio sidecar) would know to send to the waypoint, but for other clients | ||
| (such as a workload outside of the mesh) likely would not know anything about waypoint proxies and send requests directly. | ||
| When these direct calls are made, the ztunnel will "hairpin" the request to its own waypoint to ensure policies are properly enforced. |
There was a problem hiding this comment.
What exactly does "hairpin" mean? "Capture and redirect"?
There was a problem hiding this comment.
Basically
client -> ztunnel -> waypoint -> ztunnel
frankbu
reviewed
Feb 24, 2023
frankbu
reviewed
Feb 24, 2023
frankbu
reviewed
Feb 24, 2023
frankbu
reviewed
Feb 24, 2023
linsun
reviewed
Feb 27, 2023
| @@ -13,4 +13,77 @@ This page is under construction. | |||
|
|
|||
| ## Traffic routing | |||
|
|
|||
| In ambient mode, workloads can fall into 3 categories: | |||
| * Uncaptured: this is a standard pod without any mesh features enabled. | |||
| * Captured: this is a pod that has traffic intercepted by `ztunnel`. Pods can be captured by setting the `istio.io/dataplane-mode=ambient` label on a namespace. | |||
There was a problem hiding this comment.
Should we also mention the redirection annotation on the pod here @howardjohn ?
linsun
reviewed
Feb 27, 2023
Co-authored-by: Lin Sun <[email protected]>
linsun
reviewed
Feb 27, 2023
| If the destination is also captured, or otherwise has Istio proxy capabilities (such as a sidecar), the request will be upgraded to an encrypted HBONE tunnel. | ||
| If the destination has a waypoint proxy, in addition to being upgraded to HBONE, the request will instead be forwarded to that waypoint. | ||
|
|
||
| Note that in the case of a request to a `Service`, a specific endpoint will be selected to determine if it has a waypoint. |
There was a problem hiding this comment.
Is it possible to explain how the specific endpoint would be selected? Is it randomly?
There was a problem hiding this comment.
That is an implementation detail - currently its random but we will optimize it in the future. I don't mind putting it but it will change
There was a problem hiding this comment.
I see, ok, SGTM not documenting it for now.
linsun
reviewed
Feb 27, 2023
| For direct requests to `Pod`s, these are simply forwarded directly after policy is applied. | ||
|
|
||
| For requests to `Service`s, the waypoint will also apply routing and load balancing. | ||
| By default, a `Service` will simply route to itself, load balancing across its endpoints. |
There was a problem hiding this comment.
Does waypoint only route to waypoint enabled endpoints?
linsun
reviewed
Feb 27, 2023
frankbu
reviewed
Feb 27, 2023
linsun
approved these changes
Feb 27, 2023
Co-authored-by: Frank Budinsky <[email protected]>
frankbu
approved these changes
Feb 27, 2023
justedennnnn
pushed a commit
to justedennnnn/istio.io
that referenced
this pull request
Jun 29, 2023
* ambient: add traffic routing docs This fills in part of the architecture doc for ambient. Note this is intentionally low-level. This attempts to mirror https://istio.io/latest/docs/ops/configuration/traffic-management/traffic-routing/ but for ambient. * Address Frank's comments * Update content/en/docs/ops/ambient/architecture/index.md Co-authored-by: Lin Sun <[email protected]> * Update content/en/docs/ops/ambient/architecture/index.md Co-authored-by: Frank Budinsky <[email protected]> --------- Co-authored-by: Lin Sun <[email protected]> Co-authored-by: Frank Budinsky <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
This fills in part of the architecture doc for ambient.
Note this is intentionally low-level. This attempts to mirror https://istio.io/latest/docs/ops/configuration/traffic-management/traffic-routing/ but for ambient.
Please provide a description for what this PR is for.
And to help us figure out who should review this PR, please
put an X in all the areas that this PR affects.