What works in Ambient?

[Stevenjin8]

Naturally, the answer is "it depends", but we should do a better job explaining this in the docs/integrating ambient into our docs in general. Authn policy is a great example.

It makes no mention of Ambient mode, so its not clear what when policy applies. And the answer is a little complicated since L4 auth policy works if ambient is enabled, while L7 policy only applies when there is a waypoint. So its more complicated than a sidecar vs ambient question. (There are also other factors too, such as whether DNS proxying is enabled).

Another problem is that a lot of the code is sidecar specific:

$ kubectl create ns foo
$ kubectl apply -f <(istioctl kube-inject -f [samples/httpbin/httpbin.yaml](https://raw.githubusercontent.com/istio/istio/release-1.26/samples/httpbin/httpbin.yaml)) -n foo
$ kubectl apply -f <(istioctl kube-inject -f [samples/curl/curl.yaml](https://raw.githubusercontent.com/istio/istio/release-1.26/samples/curl/curl.yaml)) -n foo

What I really want to avoid is having a bunch of banners in saying "ambient mode this, ambient mode that" in our tutorials. Users should be able to copy and paste instructions line by line and have things work.

So at a high level, this is my proposal. For tutorials (i.e. tasks), add a tab to code blocks for sidecar vs ambient mode, much like how we have our own ingress APIs vs Kubernetes' Gateway APIs. This way, beginners can scroll down the page and copy-paste code blocks without having to even know what ambient is.

Reference docs are a little trickier, since they are more specific. @therealmitchconnors suggested going field by field and saying if/when it is supported, but that seems extremely tedious. Another approach we could take is going through the feature page and adding an ambient/ambient+sidecar column, but that feels too general.

cc @therealmitchconnors @grnmeira @craigbox

[Stevenjin8]

The dataplane comparison page might be a good starting point https://istio.io/latest/docs/overview/dataplane-modes/

[grnmeira]

Regarding the feature page, it does feel a bit general, but I think we need that, independently of what we decide to do with the reference docs. It's a good place for understanding the maturity of certain features in different data-plane modes. I'd suggest actually referencing that in Overview Data-plane modes, and unifying both if people think that makes sense.

[Stevenjin8]

some thoughts:

https://istio.io/latest/docs/overview/dataplane-modes/#layer-4-vs-layer-7-features specify that l4 is just ztunnel and l7 is sidecar or waypoint

retries: what is "request failure"

gateway api: not mentioned

[Stevenjin8]

@therealmitchconnors at a high level, most of this is covered in https://istio.io/latest/docs/overview/dataplane-modes/#layer-4-vs-layer-7-features, so I think here is the plan:

• add some missing entries into l4 vs l7 features
• make the above page more prominent
• Add sidecar/ambient tab to codeblocks in the tasks page (or mention if something doesn't work in ambient, such as vms)