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
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-infinispanon yourPATH. - Have valid Data Grid credentials.
Procedure
Run the
infinispan shellcommand to connect to your Data Grid cluster.oc infinispan shell <cluster_name>
NoteIf you have access to authentication secrets and there is only one Data Grid user the
kubectl-infinispanplugin automatically detects your credentials and authenticates to Data Grid. If your deployment has multiple Data Grid credentials, specify a user with the--usernameargument and enter the corresponding password when prompted.Perform CLI operations as required.
TipPress the tab key or use the
--helpargument to view available options and help text.-
Use the
quitcommand to end the remote shell session.
Additional resources
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 aLoadBalancerservice or create aRoute.
Procedure
Access the console from any browser at
$HOSTNAME:$PORT.Replace
$HOSTNAME:$PORTwith the network location where Data Grid is available.
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.
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
LoadBalancerservice, aNodePortservice, or an OpenShiftRoute. - 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.
Replace $SERVICE_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("$HOSTNAME")
.port(ConfigurationProperties.DEFAULT_HOTROD_PORT)
.security().authentication()
.username("username")
.password("changeme")
.realm("default")
.saslQop(SaslQop.AUTH)
.saslMechanism("SCRAM-SHA-512")
.ssl()
.sniHostName("$SERVICE_HOSTNAME")
.trustStoreFileName("/var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt")
.trustStoreType("pem");
hotrod-client.properties
# Connection infinispan.client.hotrod.server_list=$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 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("$HOSTNAME")
.port("$PORT")
.security().authentication()
.username("username")
.password("changeme")
.realm("default")
.saslQop(SaslQop.AUTH)
.saslMechanism("SCRAM-SHA-512")
.ssl()
.sniHostName("$SERVICE_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=$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 # 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.
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:
# 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
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 aLoadBalancerservice or create aRoute.
Procedure
Access the REST API with any HTTP client at
$HOSTNAME:$PORT/rest/v2.Replace
$HOSTNAME:$PORTwith the network location where Data Grid listens for client connections.
Additional resources
