Chapter 3. Data Grid Server endpoints

Data Grid Server endpoints provide client access to the cache manager over Hot Rod and REST protocols.

3.1. Data Grid Server endpoints

3.1.1. Hot Rod

Hot Rod is a binary TCP client-server protocol designed to provide faster data access and improved performance in comparison to text-based protocols.

Data Grid provides Hot Rod client libraries in Java, C++, C#, Node.js and other programming languages.

Topology state transfer

Data Grid uses topology caches to provide clients with cluster views. Topology caches contain entries that map internal JGroups transport addresses to exposed Hot Rod endpoints.

When client send requests, Data Grid servers compare the topology ID in request headers with the topology ID from the cache. Data Grid servers send new topology views if client have older topology IDs.

Cluster topology views allow Hot Rod clients to immediately detect when nodes join and leave, which enables dynamic load balancing and failover.

In distributed cache modes, the consistent hashing algorithm also makes it possible to route Hot Rod client requests directly to primary owners.

3.1.2. REST

Data Grid exposes a RESTful interface that allows HTTP clients to access data, monitor and maintain clusters, and perform administrative operations.

You can use standard HTTP load balancers to provide clients with load balancing and failover capabilities. However, HTTP load balancers maintain static cluster views and require manual updates when cluster topology changes occur.

3.1.3. Memcached

Data Grid provides an implementation of the Memcached text protocol for remote client access.

Important

The Memcached endpoint is deprecated and planned for removal in a future release.

The Data Grid Memcached endpoint supports clustering with replicated and distributed cache modes.

There are some Memcached client implementations, such as the Cache::Memcached Perl client, that can offer load balancing and failover detection capabilities with static lists of Data Grid server addresses that require manual updates when cluster topology changes occur.

3.1.4. Comparison of endpoint protocols

 Hot RodHTTP / REST

Topology-aware

Y

N

Hash-aware

Y

N

Encryption

Y

Y

Authentication

Y

Y

Conditional ops

Y

Y

Bulk ops

Y

N

Transactions

Y

N

Listeners

Y

N

Query

Y

Y

Execution

Y

N

Cross-site failover

Y

N

3.1.5. Hot Rod client compatibility with Data Grid Server

Data Grid Server allows you to connect Hot Rod clients with different versions. For instance during a migration or upgrade to your Data Grid cluster, the Hot Rod client version might be a lower Data Grid version than Data Grid Server.

Tip

Data Grid recommends using the latest Hot Rod client version to benefit from the most recent capabilities and security enhancements.

Data Grid 8 and later

Hot Rod protocol version 3.x automatically negotiates the highest version possible for clients with Data Grid Server.

Data Grid 7.3 and earlier

Clients that use a Hot Rod protocol version that is higher than the Data Grid Server version must set the infinispan.client.hotrod.protocol_version property.

Additional resources

3.2. Configuring Data Grid Server endpoints

Control how Hot Rod and REST endpoints bind to sockets and use security realm configuration. You can also configure multiple endpoints and disable administrative capabilities.

Note

Each unique endpoint configuration must include both a Hot Rod connector and a REST connector. Data Grid Server implicitly includes the hotrod-connector and rest-connector elements, or fields, in an endpoint configuration. You should only add these elements to custom configuration to specify authentication mechanisms for endpoints.

Prerequisites

  • Add socket bindings and security realms to your Data Grid Server configuration.

Procedure

  1. Open your Data Grid Server configuration for editing.
  2. Wrap multiple endpoint configurations with the endpoints element.
  3. Specify the socket binding that the endpoint uses with the socket-binding attribute.
  4. Specify the security realm that the endpoint uses with the security-realm attribute.

  5. Disable administrator access with the admin="false" attribute, if required.

    With this configuration users cannot access Data Grid Console or the Command Line Interface (CLI) from the endpoint.

  6. Save the changes to your configuration.

Multiple endpoint configuration

The following Data Grid Server configuration creates endpoints on separate socket bindings with dedicated security realms:

XML

<server xmlns="urn:infinispan:server:13.0">
  <endpoints>
    <endpoint socket-binding="public"
              security-realm="application-realm"
              admin="false">
    </endpoint>
    <endpoint socket-binding="private"
              security-realm="management-realm">
    </endpoint>
  </endpoints>
</server>

JSON

{
  "server": {
    "endpoints": [{
      "socket-binding": "private",
      "security-realm": "private-realm"
    }, {
      "socket-binding": "public",
      "security-realm": "default",
      "admin": "false"
    }]
  }
}

YAML

server:
  endpoints:
   - socketBinding: public
     securityRealm: application-realm
     admin: false
   - socketBinding: private
     securityRealm: management-realm

Additional resources

3.3. Endpoint connectors

Connectors configure Hot Rod and REST endpoints to use socket bindings and security realms.

Default endpoint configuration

<endpoints socket-binding="default" security-realm="default"/>

Configuration element or attributeDescription

endpoints

Wraps endpoint connector configuration.

endpoint

Declares a Data Grid Server endpoint that configures Hot Rod and REST connectors to use a socket binding and security realm.

hotrod-connector

Includes the Hot Rod endpoint in the endpoint configuration.

rest-connector

Includes the Hot Rod endpoint in the endpoint configuration.

memcached-connector

Configures the Memcached endpoint and is disabled by default.

Additional resources

3.4. Endpoint IP address filtering rules

Data Grid Server endpoints can use filtering rules that control whether clients can connect based on their IP addresses. Data Grid Server applies filtering rules in order until it finds a match for the client IP address.

A CIDR block is a compact representation of an IP address and its associated network mask. CIDR notation specifies an IP address, a slash ('/') character, and a decimal number. The decimal number is the count of leading 1 bits in the network mask. The number can also be thought of as the width, in bits, of the network prefix. The IP address in CIDR notation is always represented according to the standards for IPv4 or IPv6.

The address can denote a specific interface address, including a host identifier, such as 10.0.0.1/8, or it can be the beginning address of an entire network interface range using a host identifier of 0, as in 10.0.0.0/8 or 10/8.

For example:

  • 192.168.100.14/24 represents the IPv4 address 192.168.100.14 and its associated network prefix 192.168.100.0, or equivalently, its subnet mask 255.255.255.0, which has 24 leading 1-bits.
  • the IPv4 block 192.168.100.0/22 represents the 1024 IPv4 addresses from 192.168.100.0 to 192.168.103.255.
  • the IPv6 block 2001:db8::/48 represents the block of IPv6 addresses from 2001:db8:0:0:0:0:0:0 to 2001:db8:0:ffff:ffff:ffff:ffff:ffff.
  • ::1/128 represents the IPv6 loopback address. Its prefix length is 128 which is the number of bits in the address.

IP address filter configuration

In the following configuration, Data Grid Server accepts connections only from addresses in the 192.168.0.0/16 and 10.0.0.0/8 CIDR blocks. Data Grid Server rejects all other connections.

XML

<server xmlns="urn:infinispan:server:13.0">
  <endpoints>
    <endpoint socket-binding="default" security-realm="default">
      <ip-filter>
        <accept from="192.168.0.0/16"/>
        <accept from="10.0.0.0/8"/>
        <reject from="/0"/>
      </ip-filter>
    </endpoint>
  </endpoints>
</server>

JSON

{
  "server": {
    "endpoints": {
      "endpoint": {
        "socket-binding": "default",
        "security-realm": "default",
        "ip-filter": {
          "accept-from": ["192.168.0.0/16", "10.0.0.0/8"],
          "reject-from": "/0"
        }
      }
    }
  }
}

YAML

server:
  endpoints:
    endpoint:
      socketBinding: "default"
      securityRealm: "default"
      ipFilter:
        acceptFrom: ["192.168.0.0/16","10.0.0.0/8"]
        rejectFrom: "/0"

3.5. Inspecting and modifying rules for filtering IP addresses

Configure IP address filtering rules on Data Grid Server endpoints to accept or reject connections based on client address.

Prerequisites

  • Install Data Grid Command Line Interface (CLI).

Procedure

  1. Create a CLI connection to Data Grid Server.

  2. Inspect and modify the IP filter rules server connector ipfilter command as required.

    1. List all IP filtering rules active on a connector across the cluster: 

      server connector ipfilter ls endpoint-default

    2. Set IP filtering rules across the cluster.

      Note

      This command replaces any existing rules. 

      server connector ipfilter set endpoint-default --rules=ACCEPT/192.168.0.0/16,REJECT/10.0.0.0/8`

    3. Remove all IP filtering rules on a connector across the cluster. 

      server connector ipfilter clear endpoint-default