Chapter 10. Establishing Remote Client Connections

Connect to Data Grid clusters from the Data Grid Console, Command Line Interface (CLI), and remote clients.

10.1. Client Connection Details

Before you can connect to Data Grid, you need to retrieve the following pieces of information:

  • Service hostname
  • Port
  • Authentication credentials
  • TLS certificate, if you use encryption

Service hostnames

The service hostname depends on how you expose Data Grid on the network or if your clients are running on OpenShift.

For clients running on OpenShift, you can use the name of the internal service that Data Grid Operator creates.

For clients running outside OpenShift, the service hostname is the location URL if you use a load balancer. For a node port service, the service hostname is the node host name. For a route, the service hostname is either a custom hostname or a system-defined hostname.

Ports

Client connections on OpenShift and through load balancers use port 11222.

Node port services use a port in the range of 30000 to 60000. Routes use either port 80 (unencrypted) or 443 (encrypted).

Additional resources

10.2. Creating Data Grid Caches

To create caches when running Data Grid on OpenShift, you can:

  • Use Cache CR.
  • Create multiple caches at a time with Data Grid CLI if you do not use Cache CR.
  • Access Data Grid Console and create caches in XML or JSON format as an alternative to Cache CR or Data Grid CLI.
  • Use Hot Rod clients to create caches either programmatically or through per cache properties only if required.

Additional resources

Creating Caches with Data Grid Operator

10.3. Connecting with the Data Grid CLI

Use the command line interface (CLI) to connect to your Data Grid cluster and perform administrative operations.

The CLI is available as part of the server distribution, which you can run on your local host to establish remote connections to Data Grid clusters on OpenShift.

Note

It is possible to open a remote shell to a Data Grid node and access the CLI. 

$ oc rsh example-infinispan-0

However using the CLI in this way consumes memory allocated to the container, which can lead to out of memory exceptions.

10.3.1. Creating Caches with Data Grid CLI

Add caches to your Data Grid cluster with the CLI.

Prerequisites

  • Download the server distribution so you can run the CLI.
  • Retrieve the necessary client connection details.

Procedure

  1. Create a file with a cache configuration in XML or JSON format, for example: 

    cat > infinispan.xml<<EOF
<infinispan>
   <cache-container>
      <distributed-cache name="mycache">
         <encoding>
            <key media-type="application/x-protostream"/>
            <value media-type="application/x-protostream"/>
         </encoding>
      </distributed-cache>
   </cache-container>
</infinispan>
EOF

  2. Create a CLI connection to your Data Grid cluster. 

    $ bin/cli.sh -c https://$SERVICE_HOSTNAME:$PORT --trustall

    Replace $SERVICE_HOSTNAME:$PORT with the hostname and port where Data Grid is available on the network.

  3. Enter your Data Grid credentials when prompted.

  4. Add the cache with the create cache command and the --file option. 

    [//containers/default]> create cache --file=infinispan.xml mycache

  5. Verify the cache exists with the ls command. 

    [//containers/default]> ls caches
mycache

  6. Optionally retrieve the cache configuration with the describe command. 

    [//containers/default]> describe caches/mycache

Additional resources

10.3.2. Creating Caches in Batches

Add multiple caches with batch operations with the Data Grid CLI.

Prerequisites

  • Download the server distribution so you can run the CLI.
  • Retrieve the necessary client connection details.

Procedure

  1. Create at least one file with a cache configuration in XML or JSON format.

  2. Create a batch file, for example: 

    cat > caches.batch<<EOF
echo "connecting"
connect --username=developer --password=dIRs5cAAsHIeeRIL
echo "creating caches..."
create cache firstcache --file=infinispan-one.xml
create cache secondcache --file=infinispan-two.xml
create cache thirdcache --file=infinispan-three.xml
create cache fourthcache --file=infinispan-four.xml
echo "verifying caches"
ls caches
EOF

  3. Create the caches with the CLI. 

    $ bin/cli.sh -c https://$SERVICE_HOSTNAME:$PORT --trustall -f /tmp/caches.batch

    Replace $SERVICE_HOSTNAME:$PORT with the hostname and port where Data Grid is available on the network.

Additional resources

10.4. Accessing Data Grid Console

Access the console to create caches, perform adminstrative operations, and monitor your Data Grid clusters.

Prerequisites

  • Expose Data Grid on the network so you can access the console through a browser.
    For example, configure a load balancer service or create a route.

Procedure

  1. Access the console from any browser at $SERVICE_HOSTNAME:$PORT.

    Replace $SERVICE_HOSTNAME:$PORT with the hostname and port where Data Grid is available on the network.

  2. Enter your Data Grid credentials when prompted.

10.5. Hot Rod Clients

Hot Rod is a binary TCP protocol that Data Grid provides for high-performance data transfer capabilities with remote clients.

Client intelligence

Client intelligence refers to mechanisms the Hot Rod protocol provides so that clients can locate and send requests to Data Grid nodes.

Hot Rod clients running on OpenShift can access internal IP addresses for Data Grid nodes so you can use any client intelligence. The default intelligence, HASH_DISTRIBUTION_AWARE, is recommended because it allows clients to route requests to primary owners, which improves performance.

Hot Rod clients running outside OpenShift must use BASIC intelligence.

10.5.1. Hot Rod Configuration API

You can programmatically configure Hot Rod client connections with the ConfigurationBuilder interface.

Note

$SERVICE_HOSTNAME:$PORT denotes the hostname and port that allows access to your Data Grid cluster. You should replace these variables with the actual hostname and port for your environment.

On OpenShift

Hot Rod clients running on OpenShift can use the following configuration: 

import org.infinispan.client.hotrod.configuration.ConfigurationBuilder;
import org.infinispan.client.hotrod.configuration.SaslQop;
import org.infinispan.client.hotrod.impl.ConfigurationProperties;
...

ConfigurationBuilder builder = new ConfigurationBuilder();
      builder.addServer()
               .host("$SERVICE_HOSTNAME")
               .port(ConfigurationProperties.DEFAULT_HOTROD_PORT)
             .security().authentication()
               .username("username")
               .password("password")
               .realm("default")
               .saslQop(SaslQop.AUTH)
               .saslMechanism("SCRAM-SHA-512")
             .ssl()
               .sniHostName("$SERVICE_HOSTNAME")
               .trustStorePath("/var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt");
Outside OpenShift

Hot Rod clients running outside OpenShift can use the following configuration: 

import org.infinispan.client.hotrod.configuration.ClientIntelligence;
import org.infinispan.client.hotrod.configuration.ConfigurationBuilder;
import org.infinispan.client.hotrod.configuration.SaslQop;
...

ConfigurationBuilder builder = new ConfigurationBuilder();
      builder.addServer()
               .host("$SERVICE_HOSTNAME")
               .port("$PORT")
             .security().authentication()
               .username("username")
               .password("password")
               .realm("default")
               .saslQop(SaslQop.AUTH)
               .saslMechanism("SCRAM-SHA-512")
             .ssl()
               .sniHostName("$SERVICE_HOSTNAME")
               .trustStorePath("/path/to/tls.crt");
      builder.clientIntelligence(ClientIntelligence.BASIC);

10.5.2. Hot Rod Client Properties

You can configure Hot Rod client connections with the hotrod-client.properties file on the application classpath.

Note

$SERVICE_HOSTNAME:$PORT denotes the hostname and port that allows access to your Data Grid cluster. You should replace these variables with the actual hostname and port for your environment.

On OpenShift

Hot Rod clients running on OpenShift can use the following properties: 

# Connection
infinispan.client.hotrod.server_list=$SERVICE_HOSTNAME:$PORT

# Authentication
infinispan.client.hotrod.use_auth=true
infinispan.client.hotrod.auth_username=developer
infinispan.client.hotrod.auth_password=$PASSWORD
infinispan.client.hotrod.auth_server_name=$CLUSTER_NAME
infinispan.client.hotrod.sasl_properties.javax.security.sasl.qop=auth
infinispan.client.hotrod.sasl_mechanism=SCRAM-SHA-512

# Encryption
infinispan.client.hotrod.sni_host_name=$SERVICE_HOSTNAME
# Path to the TLS certificate.
# Clients automatically generate trust stores from certificates.
infinispan.client.hotrod.trust_store_path=/var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt
Outside OpenShift

Hot Rod clients running outside OpenShift can use the following properties: 

# Connection
infinispan.client.hotrod.server_list=$SERVICE_HOSTNAME:$PORT

# Client intelligence
infinispan.client.hotrod.client_intelligence=BASIC

# Authentication
infinispan.client.hotrod.use_auth=true
infinispan.client.hotrod.auth_username=developer
infinispan.client.hotrod.auth_password=$PASSWORD
infinispan.client.hotrod.auth_server_name=$CLUSTER_NAME
infinispan.client.hotrod.sasl_properties.javax.security.sasl.qop=auth
infinispan.client.hotrod.sasl_mechanism=SCRAM-SHA-512

# Encryption
infinispan.client.hotrod.sni_host_name=$SERVICE_HOSTNAME
# Path to the TLS certificate.
# Clients automatically generate trust stores from certificates.
infinispan.client.hotrod.trust_store_path=tls.crt

10.5.3. Creating Caches with Hot Rod Clients

You can remotely create caches on Data Grid clusters running on OpenShift with Hot Rod clients. However, Data Grid recommends that you create caches using Data Grid Console, the CLI, or with Cache CRs instead of with Hot Rod clients.

Programmatically creating caches

The following example shows how to add cache configurations to the ConfigurationBuilder and then create them with the RemoteCacheManager: 

import org.infinispan.client.hotrod.DefaultTemplate;
import org.infinispan.client.hotrod.RemoteCache;
import org.infinispan.client.hotrod.RemoteCacheManager;
...

      builder.remoteCache("my-cache")
             .templateName(DefaultTemplate.DIST_SYNC);
      builder.remoteCache("another-cache")
             .configuration("<infinispan><cache-container><distributed-cache name=\"another-cache\"><encoding media-type=\"application/x-protostream\"/></distributed-cache></cache-container></infinispan>");
      try (RemoteCacheManager cacheManager = new RemoteCacheManager(builder.build())) {
      // Get a remote cache that does not exist.
      // Rather than return null, create the cache from a template.
      RemoteCache<String, String> cache = cacheManager.getCache("my-cache");
      // Store a value.
      cache.put("hello", "world");
      // Retrieve the value and print it.
      System.out.printf("key = %s\n", cache.get("hello"));

This example shows how to create a cache named CacheWithXMLConfiguration using the XMLStringConfiguration() method to pass the cache configuration as XML: 

import org.infinispan.client.hotrod.RemoteCacheManager;
import org.infinispan.commons.configuration.XMLStringConfiguration;
...

private void createCacheWithXMLConfiguration() {
    String cacheName = "CacheWithXMLConfiguration";
    String xml = String.format("<infinispan>" +
                                  "<cache-container>" +
                                  "<distributed-cache name=\"%s\" mode=\"SYNC\">" +
                                    "<encoding media-type=\"application/x-protostream\"/>" +
                                    "<locking isolation=\"READ_COMMITTED\"/>" +
                                    "<transaction mode=\"NON_XA\"/>" +
                                    "<expiration lifespan=\"60000\" interval=\"20000\"/>" +
                                  "</distributed-cache>" +
                                  "</cache-container>" +
                                "</infinispan>"
                                , cacheName);
    manager.administration().getOrCreateCache(cacheName, new XMLStringConfiguration(xml));
    System.out.println("Cache with configuration exists or is created.");
}
Using Hot Rod client properties

When you invoke cacheManager.getCache() calls for named caches that do not exist, Data Grid creates them from the Hot Rod client properties instead of returning null.

Add cache configuration to Hot Rod client properties as in the following example: 

# Add cache configuration
infinispan.client.hotrod.cache.my-cache.template_name=org.infinispan.DIST_SYNC
infinispan.client.hotrod.cache.another-cache.configuration=<infinispan><cache-container><distributed-cache name=\"another-cache\"/></cache-container></infinispan>
infinispan.client.hotrod.cache.my-other-cache.configuration_uri=file:/path/to/configuration.xml

10.6. Accessing the REST API

Data Grid provides a RESTful interface that you can interact with using HTTP clients.

Prerequisites

  • Expose Data Grid on the network so you can access the REST API.
    For example, configure a load balancer service or create a route.

Procedure

  • Access the REST API with any HTTP client at $SERVICE_HOSTNAME:$PORT/rest/v2.

    Replace $SERVICE_HOSTNAME:$PORT with the hostname and port where Data Grid is available on the network.

Additional resources

10.7. Adding Caches to Cache service Nodes

Cache service nodes include a default cache configuration with recommended settings. This default cache lets you start using Data Grid without the need to create caches.

Note

Because the default cache provides recommended settings, you should create caches only as copies of the default. If you want multiple custom caches you should create Data Grid service nodes instead of Cache service nodes.

Procedure

  • Access the Data Grid Console and provide a copy of the default configuration in XML or JSON format.

  • Use the Data Grid CLI to create a copy from the default cache as follows: 

    [//containers/default]> create cache --template=default mycache

10.7.1. Default Cache Configuration

The default cache for Cache service nodes is as follows: 

<infinispan>
  <cache-container>
    <distributed-cache name="default" 1
                       mode="SYNC" 2
                       owners="2"> 3
      <memory storage="OFF_HEAP" 4
              max-size="<maximum_size_in_bytes>" 5
              when-full="REMOVE" /> 6
      <partition-handling when-split="ALLOW_READ_WRITES" 7
                          merge-policy="REMOVE_ALL"/> 8
    </distributed-cache>
  </cache-container>
</infinispan>
1
Names the cache instance as "default".
2
Uses synchronous distribution for storing data across the cluster.
3
Configures two replicas of each cache entry on the cluster.
4
Stores cache entries as bytes in native memory (off-heap).
5
Defines the maximum size for the data container in bytes. Data Grid Operator calculates the maximum size when it creates nodes.
6
Evicts cache entries to control the size of the data container. You can enable automatic scaling so that Data Grid Operator adds nodes when memory usage increases instead of removing entries.
7
Names a conflict resolution strategy that allows read and write operations for cache entries, even if segment owners are in different partitions.
8
Specifies a merge policy that removes entries from the cache when Data Grid detects conflicts.