25 Using the Coherence gRPC Proxy Server

The Coherence gRPC proxy is the server-side implementation of the gRPC services defined within the Coherence gRPC module. The gRPC proxy uses standard gRPC Java libraries to provide Coherence APIs over gRPC.

This chapter includes the following sections:

• Setting Up the Coherence gRPC Proxy Server
  To set up and start using the Coherence gRPC Server, you should declare it as a dependency of your project.
• Configuring the Server
  Configuring the gRPC server includes configuring the server listen address and port, SSL/TLS, and server thread pool.
• Disabling the gRPC Proxy Server
  The Coherence gRPC server starts automatically if the coherence-grpc-proxy module is on the class path (or module path).
• Deploying the Proxy Service with Helidon Microprofile gRPC Server
  If you use the Helidon Microprofile server with the microprofile gRPC server enabled, you can deploy the Coherence gRPC proxy into the Helidon gRPC server instead of the Coherence default gRPC server.

Setting Up the Coherence gRPC Proxy Server

To set up and start using the Coherence gRPC Server, you should declare it as a dependency of your project.

For example:

If using Maven, declare the server as follows:

pom.xml

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>${coherence.group.id}</groupId>
            <artifactId>coherence-bom</artifactId>
            <version>${coherence.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>${coherence.groupId}</groupId>
        <artifactId>coherence</artifactId>
    </dependency>
    <dependency>
        <groupId>${coherence.groupId}</groupId>
        <artifactId>coherence-grpc-proxy</artifactId>
    </dependency>
<dependencies>

In the pom.xml file, coherence.version property is the version of Coherence being used, and coherence.groupId property is either the Coherence commercial group id, com.oracle.coherence, or the CE group id, com.oracle.coherence.ce.

If using Gradle, declare the server as follows:

build.gradle

dependencies {
    implementation platform("${coherenceGroupId}:coherence-bom:${coherenceVersion}")

    implementation "${coherenceGroupId}:coherence"
    implementation "${coherenceGroupId}:coherence-grpc-proxy"
}

In the build.gradle file, coherenceVersion property is the version of Coherence being used, and coherenceGroupId property is either the Coherence commercial group id, com.oracle.coherence or the CE group id, com.oracle.coherence.ce.

This section includes the following topic:

• Starting the Server
  The gRPC server starts automatically when you run com.tangosol.coherence.net.Coherence (or com.tangosol.coherence.net.DefaultCacheServer). Typically, com.tangosol.coherence.net.Coherence class should be used as the application’s main class. Alternatively, you can start an instance of com.tangosol.coherence.net.Coherence by using the Bootstrap API.

Starting the Server

The gRPC server starts automatically when you run com.tangosol.coherence.net.Coherence (or com.tangosol.coherence.net.DefaultCacheServer). Typically, com.tangosol.coherence.net.Coherence class should be used as the application’s main class. Alternatively, you can start an instance of com.tangosol.coherence.net.Coherence by using the Bootstrap API.

By default, the gRPC server listens on all local addresses using an ephemeral port. Like Coherence*Extend, the endpoints that the gRPC server is bound to can be discovered by a client using the Coherence NameService. So, using ephemeral ports allows the gRPC server to start without any port clashes.

When reviewing the log output, the two log messages appear as follows:

In-Process GrpcAcceptor is now listening for connections using name "default"
GrpcAcceptor now listening for connections on 0.0.0.0:55550

The service is ready to process requests from one of the Coherence gRPC client implementations.

Configuring the Server

Configuring the gRPC server includes configuring the server listen address and port, SSL/TLS, and server thread pool.

The Coherence gRPC proxy is configured using an internal default cache configuration file named grpc-proxy-cache-config.xml that contains only a single <proxy-scheme> configuration for the gRPC proxy. You need not override the configuration file as the server can be configured with system properties and environment variables.

This section includes the following topics:

• Configuring the Server Listen Address
  
• Configuring the Server Listen Port
  
• Configuring SSL/TLS
  
• Configuring the Server Thread Pool
  

Configuring the Server Listen Address

At runtime, you can configure the address that the gRPC server binds to by setting the coherence.grpc.server.address system property or COHERENCE_GRPC_SERVER_ADDRESS environment variable.

By default, the server binds to the address 0.0.0.0 which equates to all the local host’s network interfaces.

For example, if the host had a local IP address 192.168.0.25, you can configure the server to bind to this specific address as follows:

Using system properties:

-Dcoherence.grpc.server.address=192.168.0.25

Using environment variables:

export COHERENCE_GRPC_SERVER_ADDRESS=192.168.0.25

Configuring the Server Listen Port

At runtime, you can configure the port that the gRPC server binds to by setting the coherence.grpc.server.port system property or COHERENCE_GRPC_SERVER_PORT environment variable .

For example, to configure the server to listen on port 1408:

Using system properties:

-Dcoherence.grpc.server.port=1408

Using environment variables:

export COHERENCE_GRPC_SERVER_PORT=1408

Configuring SSL/TLS

Like other Coherence services, you can configure the Coherence gRPC server to use SSL by specifying the name of a socket provider.

Named socket providers are configured in the Coherence operational configuration file (override file), tangosol-coherence-override.xml.

tangosol-coherence-override.xml file looks similar to:

<socket-providers>
      <socket-providerid="tls">
        <ssl>
          <identity-manager>
            <keysystem-property="coherence.security.key">server.key</key>
            <certsystem-property="coherence.security.cert">server.cert</cert>
          </identity-manager>
          <trust-manager>
            <certsystem-property="coherence.security.ca.cert">server-ca.cert</cert>
          </trust-manager>
        </ssl>
      </socket-provider>
    </socket-providers>

After the named socket provider has been configured, you can configure the gRPC server to use that provider by setting the coherence.grpc.server.socketprovider system property or COHERENCE_GRPC_SERVER_SOCKETPROVIDER environment variable.

For example, if a socket provider named tls has been configured in the operational configuration file, tangosol-coherence-override.xml, you can configure the gRPC server to use tls as follows:

Using system properties:

-Dcoherence.grpc.server.socketprovider=tls

Using environment variables:

export COHERENCE_GRPC_SERVER_SOCKETPROVIDER=tls

For more information about socket providers and how to configure them, see Using SSL to Secure Communication in Securing Oracle Coherence.

Configuring the Server Thread Pool

Like other Coherence services, the gRPC server uses a dynamically sized thread pool to process requests. If the dynamic sizing algorithm proves to not be optimal, you can configure the thread pool size by adjusting the minimum thread count and the maximum thread count.

This section includes the following topics:

• Setting the Minimum Thread Count
  
• Setting the Maximum Thread Count
  

Setting the Minimum Thread Count

Adjusting the minimum number of threads can be useful to deal with bursts in load.

At times, when the dynamic pool quickly deals with an increase in load, it takes some time to increase the thread count to a suitable number. Setting the minimum size ensures that there are always a certain number of threads to service load.

You can set the minimum number of threads in the pool by using the coherence.grpc.server.threads.min system property, or the COHERENCE_GRPC_SERVER_THREADS_MIN environment variable.

For example, you can set the minimum thread count to 10 as follows:

Using system properties:

-Dcoherence.grpc.server.threads.min=10

Using environment variables:

export COHERENCE_GRPC_SERVER_THREADS_MIN=10

Setting the Maximum Thread Count

Adjusting the maximum number of threads can be useful to stop the dynamic pool going too high and consuming too much CPU resource.

You can set the maximum number of threads in the pool by using the coherence.grpc.server.threads.max system property, or the COHERENCE_GRPC_SERVER_THREADS_MAX environment variable.

Note:

When you specify both maximum and minimum thread counts, you must set the maximum thread count at a higher value than the minimum thread count.

For example, you can set the maximum thread count to 20 as follows:

Using system properties:

Dcoherence.grpc.server.threads.max=20

Using environment variables:

export COHERENCE_GRPC_SERVER_THREADS_MAX=20

Disabling the gRPC Proxy Server

The Coherence gRPC server starts automatically if the coherence-grpc-proxy module is on the class path (or module path). However, you can disable the server by setting the coherence.grpc.enabled system property to false.

Deploying the Proxy Service with Helidon Microprofile gRPC Server

If you use the Helidon Microprofile server with the microprofile gRPC server enabled, you can deploy the Coherence gRPC proxy into the Helidon gRPC server instead of the Coherence default gRPC server.

For this behavior to happen automatically, set the coherence.grpc.enabled system property to false, which disables the built-in server. A built-in GrpcMpExtension implementation then deploys the proxy services to the Helidon gRPC server.

For more information about Helidon, see the Helidon Documentation.

Note:

When using the Helidon MP gRPC server, if you have not set the coherence.grpc.enabled system property to false, then both the Helidon gRPC server and the Coherence default gRPC server will start. This event can cause port binding issues unless you have configured both the servers to use different ports.