Supplementing Istio's documentation

The documentation is great to get started, but the moment you want to do s.th. more intricate the documentation fails the user IMHO. As an example: Enabling rate-limiting we are given a basic example, that enables global and/or local ratelimiting for the example-deployment. The problem arises when you want to do s.th. other than the example deployment.

The user should not have to look through the example depolyment to figure out, painfully slow I might add, what tag and configuration adheres to what value in their application.

It is good that there are links to the envoy configuration, but , as far as I understand it, istio ships a modified version. Also, some of the values appear to be istio based. Let's look at https://istio.io/latest/docs/tasks/policy-enforcement/rate-limit/ . name: "inbound|http|9080" is this a bunch of or-selectors or the actual exemplatory name of the service? If this is s.th. akin to a vhost in apache. it would be misleading and s.th. like "*:80" will actually match every vhost listening on port 80. Another example would be context: SIDECAR_OUTBOUND what is this context and are there others? I cannot find it searching over the envoy documentation, why is a rate-limiting bound to an OUTBOUND-context, that defies the purpose of the rate-limiting. What are the values available for configuration under routeConfiguration in the local example? I assume I can pass a path for rate-limiting in here, but how? e.g. I have a single service exposing a pod and I want a specific path to be rate-limited only.

A more comprehensive, old school documentation like lookup supplementing these examples is vital for a good DX IMHO, as configuration files are not directly tied to code for inspection as to what is actually possible. It would also allow the administrators to focus on the configuration without having to scour the net for examples not fully compatible with their deployment-scenario or having to read GoLang code.

// Edit Not to mention the problem that a configuration might be valid but not applicable to a service because of its complexity. traefik's documentation would be a nice example . The configurations are small, relatively independent and comprehensible not like far out stuff like "@type": type.googleapis.com/udpa.type.v1.TypedStruct where one can clearly see it is a type declaration, but not much else. Or stat_prefix: http_local_rate_limiter what is the purpose of the prefix, what degrees of freedom do I have changing it? Is it somehow related to s.th. else in the configuration(similar to app: xxxxx -tags) see type_url or the attribute envoy.filters.http.local_ratelimit.... etc.

//Edit I found s.th. along the lines I was looking for https://istio.io/latest/docs/reference/config/networking/envoy-filter/ . A link from the task-section with the example would be nice as the more in depth documentation is ordered along the lines of the components and not the order of the examples in the website, e.g. rate-limiting or tasks. But things link "typed_per_filter_config" are not explained there either.

istio / istio.io

Supplementing Istio's documentation #9453