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 to the Java, JavaScript, Python, and Go gRPC clients.

This chapter includes the following sections:

Parent topic: Getting Started with gRPC

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.group.id}</groupId>
        <artifactId>coherence</artifactId>
    </dependency>
    <dependency>
        <groupId>${coherence.group.id}</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:

Application requirements

These are POM/Gradle fragments, not complete build files. For the commercial release set the group to com.oracle.coherence and version to 26.1.0-0-0, or use the matching installed patch coordinates. Import the same BOM for all Coherence modules; do not mix independently chosen gRPC, proxy and client versions. Java 21 is the release baseline.

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

Parent topic: Using the Coherence gRPC Proxy Server

Starting the Server

The gRPC server starts automatically when you run com.tangosol.net.Coherence (or com.tangosol.net.DefaultCacheServer). Typically, com.tangosol.net.Coherence class should be used as the application’s main class. Alternatively, you can start an instance of com.tangosol.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.

Parent topic: Setting Up the Coherence gRPC Proxy Server

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:

Parent topic: Using the Coherence gRPC Proxy Server

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

Parent topic: Configuring the Server

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

Parent topic: Configuring the Server

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-provider id="tls">
        <ssl>
          <identity-manager>
            <key system-property="coherence.security.key">server.key</key>
            <cert system-property="coherence.security.cert">server.cert</cert>
          </identity-manager>
          <trust-manager>
            <cert system-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.

Application requirements

For 26.1 secure-transport enforcement, current socket-provider configuration and custom-channel responsibilities, see Requiring Secure gRPC Transport. Older credentials properties in this topic are specific to the provider/version that consumes them; do not assume they configure every current proxy/client implementation. Avoid embedding a real password in command lines, source files or logs.

Parent topic: Configuring the Server

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:

Parent topic: Configuring the Server

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.

Parent topic: Using the Coherence gRPC Proxy Server

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.

Parent topic: Using the Coherence gRPC Proxy Server

Requiring Secure gRPC Transport

Make TLS an explicit channel/server requirement and test identity failures as well as successful connections.

Global coherence.security.mode defaults to hardened, but gRPC secure transport is a separate policy. Set it explicitly when TLS is mandatory. optional is the secure-transport default; it permits compatible cleartext configurations. A selected secure socket provider with missing TLS credentials is a configuration error, not permission to fall back to plaintext.

Table 25-1 gRPC secure transport controls

Scope Property Values/default
Proxy server coherence.grpc.server.secure-transport optional (default) or required.
Named client channel coherence.grpc.channels.<name>.secure-transport optional (default) or required; use the channel selected by the deployment; the standard unnamed channel is default.
  • Configure identity/trust through the matching TLS socket provider on the server and client; set secure-transport=required to reject missing/insecure credentials. Policy alone does not create certificates.
  • Use DNS names covered by the server certificate. Keep hostname/authority verification enabled; do not solve a mismatch by using an insecure channel.
  • For mutual TLS, require client certificates and trust only the intended issuers. Configure application authorization separately from transport identity.
  • For custom ChannelProvider/prebuilt channels, enforce credentials in that provider. Test the actual channel, not just the XML policy.
  • Verify a successful connection plus failure for an untrusted issuer, hostname mismatch, absent required client certificate and cleartext attempt.

Follow Using TLS to Secure Communication for provider setup, secrets and rotation. This policy applies to gRPC; do not infer a change to Extend, metrics or management listeners.

Parent topic: Using the Coherence gRPC Proxy Server