Chapter 21. Establishing remote client connections Connect to Data Grid clusters from the Data Grid Console, Command Line Interface (CLI), and remote clients. 21.1. Client connection details Client connections to Data Grid require the following information: Hostname Port Authentication credentials, if required TLS certificate, if you use encryption Hostnames The hostname you use depends on whether clients are running on the same OpenShift cluster as Data Grid. Client applications running on the same OpenShift cluster use the internal service name for the Data Grid cluster. metadata: name: infinispan Client applications running on a different OpenShift, or outside OpenShift, use a hostname that depends on how Data Grid is exposed on the network. A LoadBalancer service uses the URL for the load balancer. A NodePort service uses the node hostname. An Red Hat OpenShift Route uses either a custom hostname that you define or a hostname that the system generates. Ports Client connections on OpenShift and a through LoadBalancer service use port 11222 . NodePort services use a port in the range of 30000 to 60000 . Routes use either port 80 (unencrypted) or 443 (encrypted). Additional resources Configuring Network Access to Data Grid Retrieving Credentials Retrieving TLS Certificates 21.2. Connecting to Data Grid clusters with remote shells Start a remote shell session to Data Grid clusters and use the command line interface (CLI) to work with Data Grid resources and perform administrative operations. Prerequisites Have kubectl-infinispan on your PATH . Have valid Data Grid credentials. Procedure Run the infinispan shell command to connect to your Data Grid cluster. Note If you have access to authentication secrets and there is only one Data Grid user the kubectl-infinispan plugin automatically detects your credentials and authenticates to Data Grid. If your deployment has multiple Data Grid credentials, specify a user with the --username argument and enter the corresponding password when prompted. Perform CLI operations as required. Tip Press the tab key or use the --help argument to view available options and help text. Use the quit command to end the remote shell session. Additional resources Using the Data Grid Command Line Interface 21.3. 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 LoadBalancer service or create a Route . Procedure Access the console from any browser at USDHOSTNAME:USDPORT . Replace USDHOSTNAME:USDPORT with the network location where Data Grid is available. Note The Data Grid Console should only be accessed via OpenShift services or an OpenShift Route exposing port 11222. 21.4. 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 The Hot Rod protocol includes a mechanism that provides clients with an up-to-date view of the cache topology. Client intelligence improves performance by reducing the number of network hops for read and write operations. Clients running in the same OpenShift cluster can access internal IP addresses for Data Grid pods so you can use any client intelligence. HASH_DISTRIBUTION_AWARE is the default intelligence mechanism and enables clients to route requests to primary owners, which provides the best performance for Hot Rod clients. Clients running on a different OpenShift, or outside OpenShift, can access Data Grid by using a LoadBalancer , NodePort , or OpenShift Route . Important Hot Rod client connections via OpenShift Route require encryption. You must configure TLS with SNI otherwise the Hot Rod connection fails. For unencrypted Hot Rod client connections, you must use a LoadBalancer service or a NodePort service. Hot Rod clients must use BASIC intelligence in the following situations: Connecting to Data Grid through a LoadBalancer service, a NodePort service, or an OpenShift Route . Failing over to a different OpenShift cluster when using cross-site replication. OpenShift cluster administrators can define network policies that restrict traffic to Data Grid. In some cases network isolation policies can require you to use BASIC intelligence even when clients are running in the same OpenShift cluster but a different namespace. 21.4.1. Hot Rod client configuration API You can programmatically configure Hot Rod client connections with the ConfigurationBuilder interface. Note Replace USDSERVICE_HOSTNAME in the following examples with the internal service name of your Data Grid cluster. metadata: name: infinispan On OpenShift ConfigurationBuilder 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("USDHOSTNAME") .port(ConfigurationProperties.DEFAULT_HOTROD_PORT) .security().authentication() .username("username") .password("changeme") .realm("default") .saslQop(SaslQop.AUTH) .saslMechanism("SCRAM-SHA-512") .ssl() .sniHostName("USDSERVICE_HOSTNAME") .trustStoreFileName("/var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt") .trustStoreType("pem"); hotrod-client.properties # Connection infinispan.client.hotrod.server_list=USDHOSTNAME:USDPORT # Authentication infinispan.client.hotrod.use_auth=true infinispan.client.hotrod.auth_username=developer infinispan.client.hotrod.auth_password=USDPASSWORD infinispan.client.hotrod.auth_server_name=USDCLUSTER_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=USDSERVICE_HOSTNAME infinispan.client.hotrod.trust_store_file_name=/var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt infinispan.client.hotrod.trust_store_type=pem Outside OpenShift ConfigurationBuilder 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("USDHOSTNAME") .port("USDPORT") .security().authentication() .username("username") .password("changeme") .realm("default") .saslQop(SaslQop.AUTH) .saslMechanism("SCRAM-SHA-512") .ssl() .sniHostName("USDSERVICE_HOSTNAME") //Create a client trust store with tls.crt from your project. .trustStoreFileName("/path/to/truststore.pkcs12") .trustStorePassword("trust_store_password") .trustStoreType("PCKS12"); builder.clientIntelligence(ClientIntelligence.BASIC); hotrod-client.properties # Connection infinispan.client.hotrod.server_list=USDHOSTNAME:USDPORT # 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=USDPASSWORD infinispan.client.hotrod.auth_server_name=USDCLUSTER_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=USDSERVICE_HOSTNAME # Create a client trust store with tls.crt from your project. infinispan.client.hotrod.trust_store_file_name=/path/to/truststore.pkcs12 infinispan.client.hotrod.trust_store_password=trust_store_password infinispan.client.hotrod.trust_store_type=PCKS12 21.4.2. Configuring Hot Rod clients for certificate authentication If you enable client certificate authentication, clients must present valid certificates when negotiating connections with Data Grid. Validate strategy If you use the Validate strategy, you must configure clients with a keystore so they can present signed certificates. You must also configure clients with Data Grid credentials and any suitable authentication mechanism. Authenticate strategy If you use the Authenticate strategy, you must configure clients with a keystore that contains signed certificates and valid Data Grid credentials as part of the distinguished name (DN). Hot Rod clients must also use the EXTERNAL authentication mechanism. Note If you enable security authorization, you should assign the Common Name (CN) from the client certificate a role with the appropriate permissions. The following example shows a Hot Rod client configuration for client certificate authentication with the Authenticate strategy: import org.infinispan.client.hotrod.configuration.ConfigurationBuilder; ... ConfigurationBuilder builder = new ConfigurationBuilder(); builder.security() .authentication() .saslMechanism("EXTERNAL") .ssl() .keyStoreFileName("/path/to/keystore") .keyStorePassword("keystorepassword".toCharArray()) .keyStoreType("PCKS12"); 21.4.3. Creating caches from 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("<distributed-cache name=\"%s\">" + "<encoding media-type=\"application/x-protostream\"/>" + "<locking isolation=\"READ_COMMITTED\"/>" + "<transaction mode=\"NON_XA\"/>" + "<expiration lifespan=\"60000\" interval=\"20000\"/>" + "</distributed-cache>" , 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 hotrod-client.properties as in the following example: 21.5. 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 LoadBalancer service or create a Route . Procedure Access the REST API with any HTTP client at USDHOSTNAME:USDPORT/rest/v2 . Replace USDHOSTNAME:USDPORT with the network location where Data Grid listens for client connections. Additional resources Data Grid REST API

Commands:
metadata: name: infinispan
infinispan shell <cluster_name>
metadata: name: infinispan
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("USDHOSTNAME") .port(ConfigurationProperties.DEFAULT_HOTROD_PORT) .security().authentication() .username("username") .password("changeme") .realm("default") .saslQop(SaslQop.AUTH) .saslMechanism("SCRAM-SHA-512") .ssl() .sniHostName("USDSERVICE_HOSTNAME") .trustStoreFileName("/var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt") .trustStoreType("pem");
Connection infinispan.client.hotrod.server_list=USDHOSTNAME:USDPORT Authentication infinispan.client.hotrod.use_auth=true infinispan.client.hotrod.auth_username=developer infinispan.client.hotrod.auth_password=USDPASSWORD infinispan.client.hotrod.auth_server_name=USDCLUSTER_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=USDSERVICE_HOSTNAME infinispan.client.hotrod.trust_store_file_name=/var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt infinispan.client.hotrod.trust_store_type=pem
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("USDHOSTNAME") .port("USDPORT") .security().authentication() .username("username") .password("changeme") .realm("default") .saslQop(SaslQop.AUTH) .saslMechanism("SCRAM-SHA-512") .ssl() .sniHostName("USDSERVICE_HOSTNAME") //Create a client trust store with tls.crt from your project. .trustStoreFileName("/path/to/truststore.pkcs12") .trustStorePassword("trust_store_password") .trustStoreType("PCKS12"); builder.clientIntelligence(ClientIntelligence.BASIC);
Connection infinispan.client.hotrod.server_list=USDHOSTNAME:USDPORT 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=USDPASSWORD infinispan.client.hotrod.auth_server_name=USDCLUSTER_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=USDSERVICE_HOSTNAME Create a client trust store with tls.crt from your project. infinispan.client.hotrod.trust_store_file_name=/path/to/truststore.pkcs12 infinispan.client.hotrod.trust_store_password=trust_store_password infinispan.client.hotrod.trust_store_type=PCKS12
import org.infinispan.client.hotrod.configuration.ConfigurationBuilder; ConfigurationBuilder builder = new ConfigurationBuilder(); builder.security() .authentication() .saslMechanism("EXTERNAL") .ssl() .keyStoreFileName("/path/to/keystore") .keyStorePassword("keystorepassword".toCharArray()) .keyStoreType("PCKS12");
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"));
import org.infinispan.client.hotrod.RemoteCacheManager; import org.infinispan.commons.configuration.XMLStringConfiguration; private void createCacheWithXMLConfiguration() { String cacheName = "CacheWithXMLConfiguration"; String xml = String.format("<distributed-cache name=\"%s\">" + "<encoding media-type=\"application/x-protostream\"/>" + "<locking isolation=\"READ_COMMITTED\"/>" + "<transaction mode=\"NON_XA\"/>" + "<expiration lifespan=\"60000\" interval=\"20000\"/>" + "</distributed-cache>" , cacheName); manager.administration().getOrCreateCache(cacheName, new XMLStringConfiguration(xml)); System.out.println("Cache with configuration exists or is created."); }
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