Documentation for grpc-1.0 and grpcClient-1.0

[wtlucy]

Feature epic: OpenLiberty/open-liberty#8637
Design document: https://ibm.box.com/shared/static/x6vy73iadmip6ix00mzhwuz2vqgqr4x2.pptx
OL Guide issue: OpenLiberty/guides-common#512
Simple sample project: https://github.com/OpenLiberty/sample-grpc

The new gRPC features need to be documented. We should provide an introduction of gRPC, and give some ideas for why it should be used how it can be worked into Java webapps. Ideally, we will cover a few topics:

Overview

gRPC is a high performance open source RPC framework which has wide adoption and support. It was built with the goal of easily and efficiently connecting (micro) services. gRPC makes use of Protocol Buffers as its Interface Design Language (IDL), allowing for simple service definition. Its transport is built on top of HTTP/2, allowing support for high performance bidirectional connections.

Like other RPC frameworks, gRPC is based on the idea of defining a service contract with explicit methods, parameters,
and return types. On the server side, a server implements the service interface (defined in a protocol buffer .proto
file). The client is provided with stubs that defines the same interfaces which are provided by the server – allowing a
client app to invoke remote service methods as if they're local.

Developers can build and deploy new gRPC-enabled apps on Open Liberty to provide new gRPC services - or to consume external gRPC services. Support for gRPC can also be extended to existing Java EE web applications: well-established application logic can be exposed via a new gRPC service, or it can be extended to make use of a newer external service.

Application requirements
Applications must package the protocol buffer compiler generated source with their application. See the grpc-sample project for an example of how to accomplish that packaging. grpc-java is provided by the Liberty runtime, so applications should not package those dependencies.

grpc-1.0 services
During app startup, Liberty will scan for implementors of io.grpc.BindableService. Those implementors will be instantiated and registered internally by Liberty. Multiple applications cannot provide the same service. Implementation classes must provide a zero-argument constructor. Any configurations specified in the server.xml via <grpc/> or on the services themselves via @io.openliberty.grpc.annotation.GrpcService will be applied to the service when it is started. Once the gRPC servlet startup is complete, Liberty will make it available on the server's standard HTTP ports.

grpcClient-1.0 clients
During app startup, Liberty scans for any server.xml <grpcClient> configuration. When app code creates a io.grpc.ManagedChannel, Liberty internally creates a wrapped ManagedChannel which has the <grpcClient> configuration applied, and returns that wrapped ManagedChannel to the client for use. The client app then uses the ManagedChannel to invoke its gRPC stubs, and any required Liberty-specific data (such as propagated headers) are passed along.

Configuration

grpc-1.0 services
gRPC services can be configured in two ways: in the server.xml via <grpc/> and via the new @io.openliberty.grpc.annotation.GrpcService. The server.xml configuration requires that a target filter be configured, so the runtime can map the configuration to the applicable gRPC service. Any server.xml serverInterceptors must be configured and packaged such that any targeted gRPC services can load the configured ServerInterceptor class.

Since gRPC is built on top of HTTP/2, additional configuration for gRPC service behavior is available via the HTTP/2 channel configuration. For more information see HTTP/2 support for Liberty

grpcClient-1.0 clients
gRPC clients can be configured via <grpcClient/> in server.xml. The server.xml configuration requires that host and optional path filters be configured, so Liberty can map the configuration to the applicable gRPC client call at runtime. Note the path filter is only applicable to the headersToPropagate configuration property. Any server.xml clientInterceptors must be configured and packaged such that any referenced gRPC clients can load the configured ClientInterceptor class.

gRPC clients can also be configured programmatically via io.grpc.ManagedChannelBuilder. For further programmatic configuration, applications can access the io.grpc.netty.NettyChannelBuilder by opting in to third-party classloader visibility.

Security

grpc-1.0 services
gRPC services can be secured via TLS. Authorization can be accomplishd by using @RolesAllowed, @DenyAll, and @PermitAll annotations on service implementations.

grpcClient-1.0 clients
gRPC client calls can be made via TLS. TLS can be configured by either mapping an sslRef in the <grpcClient/> configuration to an existing SSL configuration ID, or by configuring an ssl outboundConnection filter appropriately. The headersToPropagate configuration can be used to propagate security tokens, eg. headersToPropagate="authorization" or headersToPropagate="cookie".

Note, TLS is not supported by grpcClient-1.0 for older releases of Java 8. This is because the backing Netty
implementation requires the JDK 9+ ALPN API, which was not backported to the IBM JDK until 8.0.6.15, and the Oracle JDK until 8u251.

[chirp1]

Discussed the feature with Bill - guide versus topic info. Approving the Epic.

[dmuelle]

BLog post: https://www.openliberty.io/blog/2020/11/20/JNDI-gRPC-200012.html#grpc

[dmuelle]

user stories:

[dmuelle]

[dmuelle]

Hi @hutchig @pnickoll @mrsaldana - including you all here based on recommendations in a recent thread in openliberty-docs. I'm looking for a technical contact for Open Liberty gRPC. I'm working on this docs issue, which was opened by Bill Lucy but since he's no longer with IBM I'm looking for someone who can review the draft.

This draft is intended as a short introduction to using gRPC with Open Liberty. It is based on Bill's GA blog post from the gRPC release and on material from his original UFO presentation. It needs review to make sure it is technically accurate and provides the basic details that a developer would need to get a gRPC service or client up and running on OL.

I think the current draft does too much telling and not enough showing. Bill's initial blog post included simple Hello World examples for service and client, which I have replicated here. But his UFO contained more information (though not examples) about some of the prerequisite server.xml config you need to get up and running. If it would be helpful for users, I'd like to add code snippets for common server and client server.xml config, either to this document, or to the feature pages for the respective gRPC features. Originally, a guide was planned for gRPC but I checked with the guides team and so far it is still not started or prioritized.

The draft is here: Provide and consume gRPC services on Open Liberty. We hope to publish it with 22.0.0.5, if possible.

Let me know what you think- thanks!

[hutchig]

Hi @dmuelle (I am just back from Easter vacation so apologies for the delayed response) for you to achieve 'We hope to publish it with 22.0.0.5, if possible' by what date would you need the review and have 'code snippets for common server and client server.xml config' provided? I will get on with it in the meantime.

[hutchig]

I think, the text reads really well and is quite clear, I had the followingreview comments, none of which are significant:
(Great job I thought - so thanks for making this bit easy.)

'To enable support for gRPC, add the gRPC or gRPC Client feature to your server.xml file.'
might be an example of tell not show in that the real feature names might be better as the literla text used
in the sentence of course will not work?
But the actual names like 'grpcClient-1.0' and 'grpc-1.0' seem a bit ugly to me in this context and
also the versions might change.
(Later on in 'Try it out' there IS a link to https://docs-draft-openlibertyio.mybluemix.net/docs/latest/reference/feature/grpc-1.0.html which clarifies this so perhaps OK after all.)
(I think that a feature called 'grpc' that enables both and just uses
the latest available version for development purposes would be friendly/helpful but it does not exist.)

What is not clear in the docs is if the (server) grpc feature enables 100% of the grpcClient feature's features. (i.e. a server can always also be a client without having grpcClient in the server.xml.) I will come back with an answer on that.

Regarding 'it becomes accessible to remote gRPC clients on the configured HTTP ports.' I think it might help to have an example to clarify, if there is any, gRPC bits of the port config and if so how to do this.

It would be helpful if the first occurrence of 'grpc element' had a hyperlinked 'grpc' in the way that the second on does.

Similarly for '@GrpcService' (not sure if https://www.ibm.com/docs/api/v1/content/SSD28V_liberty/com.ibm.websphere.javadoc.liberty.doc/io.openliberty.grpc.1.0_1.0-javadoc/io/openliberty/grpc/annotation/GrpcService.html?view=embed is the best place of if there is a better one).

In https://docs-draft-openlibertyio.mybluemix.net/docs/latest/reference/config/grpc.html it is not clear if 'GRPC target endpoint' is a url/port/class/endpoint from that page so I agree an example is needed and perhaps a little bit more about what is meant by 'endpoint' on that page.

I think in 'without needing to provide the supporting client libraries.' we are meaning 'without needing to provide the supporting grpc client libraries.' - for example we say above there 'A web application must provide a client implementation...' meaning the application client and generated service stubs.

The ManagedChannel hyperlink destination would be better as https://grpc.github.io/grpc-java/javadoc/io/grpc/ManagedChannel.html rther than the 'class-use' equivalent.

The grpcClient hyperlink goes to https://docs-draft-openlibertyio.mybluemix.net/docs/latest/reference/config/grpcClient.html but nowhere there does it enable the users to 'specify the [grpcClient]element in your server.xml' as there is no note of the required text 'grpcClient-1.0' that the user needs to know.

Early on we have 'grpc' then later 'gRPC'?

I will check on having "headersToPropagate="cookie"." having an effect to 'propagate security tokens,'.

"You don’t need to provide any other libraries the application." ->
"You don’t need to provide any other libraries with the application."

I will provide some further snippets of relevant actual config elements that fit in with the text.

[dmuelle]

Thanks for reviewing @hutchig - i went ahead and made a few initial edits based on your comments.

Provide and consume gRPC services on Open Liberty.

• It would be helpful if the first occurrence of 'grpc element' had a hyperlinked 'grpc' in the way that the second on does.
• Similarly for '@GrpcService'
• I think in 'without needing to provide the supporting client libraries.' we are meaning 'without needing to provide the supporting grpc client libraries.'
• The ManagedChannel hyperlink destination would be better as https://grpc.github.io/grpc-java/javadoc/io/grpc/ManagedChannel.html rther than the 'class-use' equivalent.
• The grpcClient hyperlink goes to https://docs-draft-openlibertyio.mybluemix.net/docs/latest/reference/config/grpcClient.html but nowhere there does it enable the users to 'specify the [grpcClient]element in your server.xml' as there is no note of the required text 'grpcClient-1.0' that the user needs to know. (added link to the feature and stated that you must enable it)
• "You don’t need to provide any other libraries with the application."

a couple points of clarification-

• for feature references in the docs, we generally use the text name of the feature with an unversioned "macro" linking syntax that automatically defaults to whatever the latest version of the feature is- this prevents the docs from going out of date when a new version of a feature is added. We generally only use the code name of the feature or the feature version when the info is specific to a particular version of a feature for which multiple versions exist.
• In this doc "gRPC" is used for any text reference to the framework or a feature name. However, "grpc" (and "grpcClient") is used to refer to any configuration elements, which is consistent with the configuration syntax.

Thanks again, I'll update the doc further once you have a chance to add the examples you mentioned. The docs cutoff for the 22.0.0.5 release is Thursday 5/2, but it's not a problem to wait until 22.0.0.6 to publish if needed.

[ramkumar-k-9286]

Peer Review

https://docs-draft-openlibertyio.mybluemix.net/docs/latest/grpc-services.html

---

Acrolinx is picking up Consume and asking to use a simpler word like USE. Ignoring it as this seems more like usage and used multiple times including the heading

---

The gRPC framework was designed to efficiently connect cloud-native applications.

Suggested: The gRPC framework was designed to efficiently connect cloud-native applications.

Q: Should linking not be for [gRPC framework]? else, we could have introduced a link in the very first paragraph when gRPC is mentioned the very first time?

---

Multiple links for gRPC to different pages might confuse the reader. Should we correct it this way?

The gRPC framework was designed to efficiently connect cloud-native applications.
--->
The gRPC framework was designed to efficiently connect cloud-native applications.

The gRPC feature enables web applications to define and provide gRPC services
--->
The gRPC feature enables web applications to define and provide gRPC services

Any configurations that are specified in the grpc element in your server.xml file....
--->
Any configurations that are specified in the grpc element in your server.xml file....

If you configure gRPC in your server.xml file, you must specify the target attribute for the grpc element.
--->
If you configure gRPC in your server.xml file, you must specify the target attribute for the grpc element.

---

Any required Open Liberty-specific data, such as propagated headers, are passed along.
--->
Any Open Liberty-specific data that is needed, such as propagated headers, are passed along.

---

I remember in my prev comments - you said we can use words like don't. But,is this better?

You don’t need to provide any other libraries with the application.
--->
You need not provide any other libraries with the application.

---

In our discussions earlier, I remember that you had said that we add a link the first time an item is mentioned and then we don't.

Here, I see multiple repetitions links of gRPC clients, gRPC feature etc. --> is this done on purpose?

---

All the required gRPC client libraries are provided by the gRPC Client feature.
--->
All the gRPC client libraries that are needed, are provided by the gRPC Client feature.

---

[dmuelle]

changes are on vNext and will publish with the 22.0.0.5 docs release- closing this issue.

[dmuelle]

opened #5463 to track enhancements that will be added to this topic in a future release