Add ORCA specification

[AndresGuedez]

Add a standalone ORCA specification under the top-level orca/ directory.

This specification is intended to be continuously updated as the format evolves.

Signed-off-by: Andres Guedez [email protected]

[markdroth]

Thanks for updating this!

Please let me know if you have any questions about any of this.

[markdroth]

Please move all of this to a top-level "doc" directory (i.e., instead of orca/, it should be doc/orca/).

[markdroth]

s/gRPC-LB/gRPC/

[markdroth]

UDPA was an alternate name that we were pursuing for xDS for a while, but it's been dropped. I think we should just remove the "in the Universal Data Plane API (UDPA)" part -- it's clear enough what EDS is.

[markdroth]

The repo differs by language:

• C-core: https://github.com/grpc/grpc
• Java: https://github.com/grpc/grpc-java
• Go: https://github.com/grpc/grpc-go

[markdroth]

I think this description is a little too xDS-centric: it describes ORCA solely in the context of ORCA-to-LRS propagation, even though ORCA can be used without using xDS at all.

I would like to see this section re-written to explain how ORCA can be used to share data between endpoints and clients for things like client-side WRR. We can then add a section at the end to show how it can be used in conjunction with xDS by propagating ORCA data into LRS load reports.

[markdroth]

This paragraph seems to describe a possible future improvement, not something that's part of the existing ORCA spec. I suggest either removing it or moving it to a "Possible future improvements" section.

[markdroth]

I think we need to provide some guidance about when it's useful to choose per-request vs. OOB reporting.

I think we should recommend that the vast majority of applications use per-request reporting. OOB reporting should be considered only for traffic patterns that do not result in per-request reports being delivered often enough to stay fresh, such as a client with very sparse traffic or an application whose traffic is mostly long-running streams.

We should also point out that OOB reporting is good for utilization but doesn't make much sense for query cost reporting.

[markdroth]

I think this is true only if the sidecar is capable of determining the metrics that the endpoint wishes to report to its clients. For example, this would probably work for things like CPU or memory utilization, which the sidecar can determine in a fairly generic way. But it won't work for application-specific things, like custom utilization metrics or query cost metrics -- those will always require cooperation on the part of the application.

[markdroth]

It may also be useful to refer to the following designs as well:

• gRFC A58: Client-Side Weighted Round Robin
• gRFC A64: xDS LRS Custom Metrics Support
• (pending) gRFC A85: Changes to xDS LRS Custom Metrics Support

[markdroth]

I think this section also needs to be updated, since it no longer seems that relevant as currently written. In general, I think users are not going to choose a sidecar or library model based solely on ORCA; instead, they will probably have one of those models already and will want to know what the options are for adding ORCA support.

I think what we should be explaining here is that there are cases where a smart data plane like Envoy or gRPC can handle ORCA for you, transparently to the application, and there are other cases where the application will need to generate the ORCA data directly.