search

istio / istio.io

Source for the istio.io site
https://istio.io/
Apache License 2.0
761 stars 1.53k forks source link

Review docs with regard to Gateway API moving to Beta #15043

Open craigbox opened 4 months ago

craigbox commented 4 months ago

Ambient mode requires you to configure your routes with the Gateway API. This is in Beta in 1.22, and I also understand the GAMMA work has all moved to the stable channel.

I've removed

Configuring internal mesh traffic using the Gateway API is an experimental feature currently under development.

from /docs/tasks/traffic-management/ingress/gateway-api/index.md, but the fact this path has "ingress" in it, means we haven't updated the docs to reflect that Gateway API is now Beta for mesh traffic too.

The gateway-api-gamma-support.md boilerplate also says

Configure Istio to read the alpha Gateway API resources by setting the PILOT_ENABLE_ALPHA_GATEWAY_API environment variable to true when installing Istio:

Could someone please go through and check which of these instructions are still necessary for 1.22?

We can then go on and look at how to revamp the docs per #14229, but probably not before the launch/

howardjohn commented 4 months ago

PILOT_ENABLE_ALPHA_GATEWAY_API is about APIs that are not v1 in gw. Tcproute and tlsroute mostly.

this is 100% orthogonal from mesh support. mesh support has no API changes at all. The GW 1.1 release (coming in a few days) just declared it stable, but it has no API changes (and never did since day 0).

Istio 1.22 should claim mesh with gateway as beta.

That doesn't change that some APIs are alpha upstream and require an explicit opt in

linsun commented 4 months ago

How do we feel about TCPRoute and TLSRoute for mesh support given it requires enablement via PILOT_ENABLE_ALPHA_GATEWAY_API? Should we still claim beta for it? see https://preliminary.istio.io/latest/docs/ambient/usage/waypoint/#attachl7policies

howardjohn commented 4 months ago

No. We should probably say those 2 are alpha and maybe say "alpha resources are due to the resources themselves being alpha"

linsun commented 4 months ago

Sounds good, thinking the same too! I'll submit a quick PR to get it updated.

craigbox commented 4 months ago

if TCPRoute and TLSRoute are going to be in Alpha for a while because Istio is the only implementation, should we make it so hard for people to use them? 🤔

howardjohn commented 4 months ago

Problem is alpha -> stable promotion basically totally breaks in Gateway API's versioning model. Its not like Istio's model currently

howardjohn commented 4 months ago

Oh but we put that everywhere. We should really not do that. A page like https://preliminary.istio.io/latest/docs/tasks/traffic-management/request-routing/ has no business telling users to turn on alpha!! it doesn't need it.

What we should do is on the few pages that do, say "This feature of GW API is alpha. We recommend you don't use it yet. If you do want to, here is how..."