Document 3scale Istio Adapter 2.0

The 3scale Istio Mixer Adapter will ship a new version in the Service Mesh 2.0 product. This change requires documenting the backend cache that is now included. I will try to summarise what the documentation should convey, so hopefully we can partially use the text below and edit it into proper documentation.

Note: the new functionality will be disabled by default because it is only a good trade-off in certain circumstances.

Highly technical details of the backend cache can be found at https://github.com/3scale/3scale-authorizer/blob/ca62e09fad380b4840b4cff0d118a2cb3e34e368/pkg/backend/v1/docs/README.md, but those are mostly meant for developers rather than end users. There you can find, however, a couple of useful diagrams for product documentation, namely the AuthRep and Flushing diagrams, as they can be informational to show the logic followed internally by the backend cache to deal with the requests to the adapter (they are only authreps, and the flushes are always needed to contact the 3scale API manager).

Users should not necessarily be concerned about these technical details, although advanced users might find them interesting. Instead they should know this functionality trades correctness (inaccuracy in rate limiting and potential loss of hits since the last flush performed) for low latency (quicker responses) and higher consumption of resources (processor and memory).

Whenever users find that the latencies to access the services managed by the adapter are high, they can enable the backend cache (disabled by default) to stop the adapter from constantly checking with the 3scale API manager for request authorizations hence lowering latencies. This will create an in-memory cache of 3scale authorizations in order for the adapter to store authorization information and reuse it before trying to contact the 3scale API manager for authorizations, meaning that such authorizations should be generally returned in a quicker fashion.

This cache is indicated for cases in which the 3scale API manager is hosted far away from the service mesh running the adapter in terms of network latency. This is generally the case with the SaaS platform, but also if a user hosts their 3scale API manager in another cluster located in a different geographical area, in a different availability zone, or just in any case where the networking overhead to reach the 3scale API manager is noticeable.

The settings that configure the cache are documented at https://github.com/3scale/3scale-istio-adapter/blob/v2.0.1/cmd/server/README.md where the last 3 settings control the enabling, flush interval (the time in between consecutive attempts to flush cache data to the API manager) and the default failure policy (whether to allow/open or deny/close requests to the services when there is not enough cached data to know and the 3scale API manager cannot be reached for whatever reason).

Additionally it is important to note that these settings no longer use the THREESCALE_ prefix, so the rest of the settings must also be renamed in existing documentation for this release. It's also worth it to check that default values match all the existing values in the product documentation.

Finally, there are incompatible changes (since the previous releases in Service Mesh 1.X):

In Prometheus, metrics have been renamed, with one addition for the backend cache, so that the following metrics exist for this release:

• threescale_latency: Histogram. Request latency between adapter and 3scale.
• threescale_http_total: Counter. HTTP Status response codes for requests to 3scale backend.
• threescale_system_cache_hits: Counter. Total number of requests to 3scale system fetched from the configuration cache.
• threescale_backend_cache_hits. Counter. Total number of requests to 3scale backend fetched from the backend cache.

In behaviour, the adapter has changes a few things to more closely emulate the behaviour of Apicast when the following situations occur:

• When a request can not match any mapping rule defined, the returned HTTP code is 404 Not Found (was 403 Forbidden).
• When a request is denied because it goes over limits, the returned HTTP code is 429 Too Many Requests (was 403 Forbidden).
• When generating default templates via the CLI, it will use underscores rather than dashes for the headers (ie. user_key rather than user-key).

Hopefully that's a good summary to integrate in docs. Ping me for any clarifications!