WIP first pass for ambient api page

[linsun]

Part of istio/istio#52698

Reviewers

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

[linsun]

Anything else should be added to this page @howardjohn @ilrudie @keithmattix @louiscryan ?

[keithmattix]

HTTPRoute is GA and so is Istio's support for it generally. If this is documentation for Ambient GA, shouldn't this status be GA as well?

[keithmattix]

I actually have no idea what this does

[bleggett]

It's undocumented/WIP/experimental AFAIK: istio/istio#50235

I'd be in favor of simply not mentioning it in this doc at all at this time.

[keithmattix]

Oh yeah I'd leave this completely undocumented; I don't even know if I see sandwich on istio.io anywhere

[keithmattix]

Similar to comment below: if this is GA documentation, these labels should be GA

[howardjohn]

I would drop this and annotations, its already documented on a dedicated page (istio/api#3307 is important though)

[linsun]

My intent is to have everything in one page while linking to the official API reference page, so users don't need to go through 100 labels/annotations to identify which ones (in fact only a few of them) are ambient related.

[keithmattix]

Maybe add a sentence here about how the project recommends using Gateway API as the default and only using these resources when you need to. And maybe sort the resources in order of safety just for subliminal messaging (e.g. AuthZ policy first, then ServiceEntry, then DestinationRule, etc.).

[keithmattix]

These 3 (DR, SE, and AP) should be GA

[craigbox]

and the links to Istio APIs shouldn't go to the Gateway API site?

[bleggett]

Is this designed to document

• labels/annos that are stable/GA (and thus likely already documented elsewhere)?
• labels/annos that are not stable/GA (and thus likely not already documented elsewhere)?
• both?

Perhaps we simply should not document unstable annos/labels. If they're important enough to surface to end-users, that's maybe a good signal they should be stabilized and documented.

(if we just want an inventory of all the unstable candidate annos/labels for our own purposes, that maybe can just be in a dev wiki and not user-facing docs).

Otherwise, mentioning them here probably just helps codify them as "supported" when they may in fact be entirely unused/associated with WIP features, and we may not want that? In general I feel like documenting alpha anything in user-facing docs is a bad habit we should always avoid.

[linsun]

Is this designed to document

* labels/annos that _are_ stable/GA (and thus likely already documented elsewhere)?

* labels/annos that are _not_ stable/GA (and thus likely not already documented elsewhere)?

* both?

Perhaps we simply should not document unstable annos/labels. If they're important enough to surface to end-users, that's maybe a good signal they should be stabilized and documented.

(if we just want an inventory of all the unstable candidate annos/labels for our own purposes, that maybe can just be in a dev wiki and not user-facing docs).

Otherwise, mentioning them here probably just helps codify them as "supported" when they may in fact be entirely unused/associated with WIP features, and we may not want that? In general I feel like documenting alpha anything in user-facing docs is a bad habit we should always avoid.

The intention is to have 1 single page on ambient related APIs so user can easily understand what APIs are for ambient and their feature status. Yes, we probably have the labels/annotations documented elsewhere but I felt would be good to have everything in one page. Some of them could be alpha as that is the current state so users are well informed when they choose to use an alpha API.

[bleggett]

Some of them could be alpha as that is the current state so users are well informed when they choose to use an alpha API.

I don't think any alpha annotations or labels are required for ambient GA usage, correct?

I think, based on the actual feature definitions we always have had which are pretty clear that alpha means "general public should not use", we simply should never document any labels or annotations that are not Beta or higher.

If this causes a problem, or someone needs that label or annotation, the relevant non-beta labels or annotations should be promoted to beta or better, and documented at that time.

That way we can point at this doc and simply say "if it's not listed here, it's Alpha or worse".

(the ship has probably sailed on doing this for Istio custom resource APIs, but for labels and annotations specifically, I think it makes a lot of sense)

[keithmattix]

I don't think any alpha annotations or labels are required for ambient GA usage, correct?

Put another way, if we require alpha labels/annotations for ambient GA usage, then Ambient's not at GA quality.

[bleggett]

Yeah and since

• https://github.com/istio/api/blob/master/label/labels.yaml
• https://github.com/istio/api/blob/master/annotation/annotations.yaml

already exist as "unstable" developer documentation for Alpha-or-below labels/annotations, I don't see the need to mention Alpha-or-below labels/annotations in the user facing docs at all - that just confuses people, I feel. Better to only list the stable ones and call it a day.

Is it stable? --> do you see it referenced in this user-facing doc?

• yes? then it's stable (Beta or better).
• no? then it's not (except for EnvoyFilter) and you shouldn't use it.

I don't think we should write istio.io documentation for anything Alpha-or-below, as a general rule (EnvoyFilter probably being the really major exception).

If we want to refer to them in user-facing docs they should be Beta or higher, which seems like a perfectly reasonable forcing function for stabilizing things (and for not writing docs around features that haven't stabilized, thereby creating the expectation we will support them as-is).