Docs for bookinfo-ambient

[Stevenjin8]

Description

Part of #16494. A lot of tasks/tutorials say "set up bookinfo", so this might be a good place to start and get early feedback, as later PRs will probably look like this.

For the bookinfo-waypoint.yaml file, see istio/istio#56357

Reviewers

• Ambient
• Docs
• Installation
• Networking
• Performance and Scalability
• Extensions and Telemetry
• Security
• Test and Release
• User Experience
• Developer Infrastructure
• Localization/Translation

[Stevenjin8]

Suggested change

	If you using a cloud provider, please ensure your cluster has at least 4 nodes, each with 4GB of memory and 4 CPUS.
	If you using a cloud provider, please ensure your cluster has at least 4 nodes, each with at least 4GB of memory and 4 CPUS.

[craigbox]

"CPUs".

TBH this is really high for an app that does ~nothing. Is this still a relevant recommendation, and is it to do with reservations?

[Stevenjin8]

Honestly, I just threw a number out there that I thought would be around that of a "Standard GKE Node". Open to suggestions

[Stevenjin8]

TODO: diagram with ambient

[istio-testing]

@Stevenjin8: The following tests failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name	Commit	Details	Required	Rerun command
lint_istio.io	d69538c	link	true	/test lint
doc.test.profile-demo_istio.io	d69538c	link	true	/test doc.test.profile-demo

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. I understand the commands that are listed here.

[craigbox]

https://deploy-preview-16500--preliminary-istio.netlify.app/latest/docs/examples/bookinfo/

I like the idea of "Sidecar mode' and "Ambient mode" tab.
I feel we start getting confused when we later on have an "Istio Gateway" and "Gateway API" tab. Which do I use based on which mode?

Is it possible to land the ambient mode changes without having a (three?) way matrix about "Sidecar/Ingress", "Sidecar/Gateway", "Ambient/Gateway" — not to mention if we also support VirtualService in the docs.

[Stevenjin8]

https://deploy-preview-16500--preliminary-istio.netlify.app/latest/docs/examples/bookinfo/

I like the idea of "Sidecar mode' and "Ambient mode" tab. I feel we start getting confused when we later on have an "Istio Gateway" and "Gateway API" tab. Which do I use based on which mode?

Is it possible to land the ambient mode changes without having a (three?) way matrix about "Sidecar/Ingress", "Sidecar/Gateway", "Ambient/Gateway" — not to mention if we also support VirtualService in the docs.

I'm not sure I understand. There are four possible views of the page: {sidecar,ambient} x { ingress, gateway}. The dataplane mode tab group is independent of the gateway/ingress api tab group.

I do think its fair to say that this introduces quite a bit of complexity to a getting started page, but I think its a good compromise.

• From the POV of a first time user, the can scroll down the page and not worry about dataplane modes or gateway/ingress apis.
• From the POV of a user starting out from ambient, the docs are one click away from what they are looking for, and they can just copy paste
• Same for ingress/gateway api

The page contains all the information to get started with bookinfo with various combinations of our API without overwhelming first time users.

At some point, we have multiple APIs that do the same thing, and unless we want do omit some APIs from parts of the docs, there will be some complexity in the docs. (But maybe making some omissions isn't too bad).

[Stevenjin8]

@craigbox I think I see what you mean now because we don't support istio ingress apis with ambient. @keithmattix suggested that we get rid of istio ingress apis all together in getting started docs. However, we would still have this issue in later pages such as https://istio.io/latest/docs/tasks/traffic-management/traffic-shifting/ because we do support istio apis and gateway apis for

[Stevenjin8]

It seems like we already have a whole getting started flow with istio ambient

• https://istio.io/latest/docs/ambient/getting-started/
• https://istio.io/latest/docs/ambient/getting-started/deploy-sample-app/
• https://istio.io/latest/docs/ambient/getting-started/secure-and-visualize/
• https://istio.io/latest/docs/ambient/getting-started/enforce-auth-policies/

Might have to rethink how we're approaching this...

[craigbox]

I don't want to dissuade you from incremental improvement, but I do think we need a plan for how to handle this holistically. For example, if we were to deprioritise the Istio ingress gateway then we can work out how to keep all the docs related to it in a single place, and use Gateway API docs throughout.

Likewise, if there was a point we could make the Gateway API the default for sidecar mode configuration we would be in a much better place.

Then, we have a broader question of: is it better for a user of Istio to be given a choice on every screen they see, or to have two different hierarchies, which duplicates the information. To me, it hinges on how different sidecar and ambient mode actually are from each other (see #16494).

[keithmattix]

Likewise, if there was a point we could make the Gateway API the default for sidecar mode configuration we would be in a much better place

I think we're approaching the point where we need to make this decision. It'll simplify things for new users and improve our documentation

[Stevenjin8]

That's fair. So stepping back the question that started all this is what works in ambient, and going through all the examples and having them work with both dataplane modes is too ambitious (or more ambitious than I would like to be). Maybe we are doing better than I think we are with the dataplane comparison page