WIP first pass for ambient api page

[linsun]

Part of https://github.com/istio/istio/issues/52698

Reviewers

• [x] 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 ?

[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).

[linsun]

Thanks to everyone for the great feedback, I decided to leave the annotations out as they are alpha and many are not user facing anyway. Still waiting for label reference to show up in our doc to refer to add links to it, otherwise should be good to go.

[linsun]

Thanks to everyone for the great feedback, I decided to leave the annotations out as they are alpha and many are not user facing anyway. Still waiting for label reference to show up in our doc to refer to add links to it, otherwise should be good to go.

I don't see specific label reference shown up yet, so going to get this one in first and update it later on when the specific labels are available.

[dhawton]

For GA, we don't seem to define that anywhere but we do define Stable (https://istio.io/latest/docs/releases/feature-stages/). Should we use Stable over "GA" since it's documented?

[linsun]

For GA, we don't seem to define that anywhere but we do define Stable (https://istio.io/latest/docs/releases/feature-stages/). Should we use Stable over "GA" since it's documented?

Good point, though my personal preference is GA as that is what everyone cares about :)

[linsun]

@craigbox can you review/approve? Thanks!

[craigbox]

• putting the file where you have it makes the overview look odd.
• I think we should use "stable" because features are GA, labels are not.
• What people really want to see is a list of what features are GA. Could that be on this page?
• probably want to lowercase apis
• I can't believe that @keithmattix is letting EnvoyFilter onto this page
• likewise, we need a better story about whether VirtualService is supported forever, until a migration is complete, not if also used with HTTPRoute, etc

I would be inclined for this content to live on https://istio.io/latest/docs/releases/feature-stages/ if it's to be encyclopaedic

[linsun]

We are preparing ambient GA blog, i think this content may be best to host on the ambient GA blog. Then we can decide if we should use stable or GA and where to host it. any objections?

[linsun]

Updated GA to stable. Checked with ambient meeting, folks are good with this to be merged as a first pass. @craigbox thanks for your review, feel free to move this to a better location as you see fit. I checked API vs api in istio.io, i saw lots of returns for API so i will keep uppercase for now.

What people really want to see is a list of what features are GA.

Will have it on the ambient GA blog which I sent you a copy for review. I'm not opposed to copy it here as well.

[linsun]

putting the file where you have it makes the overview look odd.

good catch, let me look info it :)

[linsun]

putting the file where you have it makes the overview look odd.

good catch, let me look info it :)

This should be resolved now :)

[craigbox]

Second pass, see https://github.com/istio/istio.io/pull/15879. I suggest we take that one instead.

[linsun]

closing this as Craig is reworking on the new PR.