Ambient usage guide is blank

[linsun]

https://preliminary.istio.io/latest/docs/ops/ambient/usage/ should explain how users can use ambient using bookinfo, which are pretty much covered in our get started guide.

Do we still need to do this page? @howardjohn

[howardjohn]

It should contain a lot more info. The other is demo/quickstart. We need to explain how to operate ambient. Things like how to attach policies to waypoints, when you should use a waypoint vs sidecar vs neither, etc IMO.

Obviously an empty page isn't helping anyone right now, though :slightly_smiling_face: . But we do need more content

[srampal]

@linsun @howardjohn I could take a crack at this as a first issue. Feel free to assign to me.

[srampal]

@howardjohn @linsun @keithmattix

1) Please clarify how the desired content for the page targeted for this PR is to be different from the Ambient Getting Started page and what is the list of topics you would like to see added here.
2) More broadly, should all docs content for Ambient be under the Istio->Operations->Ambient Mesh page only ? (which is the case now) or should pointers to Ambient also be present under other Istio sections such as Istio->Concepts or Istio->Setup etc ? Would be good to agree on a clear docs plan keeping those into account if needed. Please provide a summary of your desired high level content layout for Ambient and list of sub-topics. If easier, we can have a short call offline first to discuss.

[linsun]

@srampal we would love ambient content to be merged to usual istio page but when we started, we wanted dedicated page to build our contents as it allow us to iterate faster.

For usage, I suggest us to have the following topics:

• mTLS, explain what is needed to configure this and which components are required. explain if mtls is enabled by default and if it is enforced always. (tie into the peer auth policy @keithmattix worked on).
• waypoint proxy, explain how to enforce L7 policy. -- we could potentially cover a lot of L7 policies here from auth policy to traffic policy to some of the telemetry and wasm policy.
• explain when to continue use sidecars.

[srampal]

Started a WIP draft PR with a skeleton of the type of content to be added. Will add additional content based on feedback and discussions with the community on the documentation plan and structure.

@howardjohn @linsun or anyone please provide your comments on the high level skeleton.

https://github.com/istio/istio.io/pull/13635

[craigbox]

This issue has been submitted for an LFX mentorship. Please don't comment on this issue if you're looking to apply. If you need to ask questions about it, please follow these steps:

• learn about Istio and what it is
• read the blog posts announcing Ambient Mesh
• look at what documentation there is for Ambient (not much!)
• install the sample
• note what you would have put in the documentation
• ask any questions in the Istio Slack on #docs.

Any other information for us should go into your application, which is submitted through the link above. The best proposal will undoubtedly show that you've done some research, and know what you want to work on. We're sorry but we can't help write individual applications.

Good luck!

[srampal]

@craigbox and anyone ... fyi, this issue was assigned to me and I am continuing to work on it. Since it was later also submitted for LFX mentorship after I was already working on it, I have broken down the work unto multiple sub-tasks and sub-guides so that multiple people can work on in addition to what I am doing. Currently we have multiple people working on the multiple sub-tasks already, please check with me first for any further info and to avoid duplication of work.

[craigbox]

@srampal we quietly hoped you would agree to be the mentor for the LFX project 😁

[howardjohn]

fixed