Chapter 2. Migrating Data Grid Server deployments

Data Grid Server 8 is:

The transition to a cloud-native architecture means that Data Grid Server 8 is no longer based on Red Hat JBoss Enterprise Application Platform (EAP). Instead Data Grid Server 8 is based on the Netty project’s client/server framework.

This change affects migration from previous versions because many of the facilities that integration with EAP provided are no longer relevant to Data Grid 8 or have changed.

For instance, while complexity of server configuration is greatly reduced in comparison to previous releases, you do need to adapt your existing configuration to a new schema. Data Grid 8 also provides more of a convention for server configuration than in previous versions where it was possible to achieve much more granular configuration. Additionally Data Grid Server no longer leverages Domain Mode to centrally manage configuration.

The Data Grid team acknowledge that these configuration changes place additional effort on our customers to migrate their existing clusters to Data Grid 8.

We believe that it is better to use container orchestration platforms, such as Red Hat OpenShift, to provision and administer Data Grid clusters along with automation engines, such as Red Hat Ansible, to manage Data Grid configuration. These technologies offer greater flexibility in that they are more generic and suitable for multiple disparate systems, rather than solutions that are more specific to Data Grid.

In terms of migration to Data Grid 8, it is worth noting that solutions like Red Hat Ansible are helpful with large-scale configuration deployment. However, that tooling might not necessarily aid the actual migration of your existing Data Grid configuration.

Data Grid provides a scalable data layer that lets you intelligently and efficiently utilize available computing resources. To achieve this with Data Grid Server deployments, configuration is separated into two layers: dynamic and static.

Dynamic configuration

Dynamic configuration is mutable, changing at runtime as you create caches and add and remove nodes to and from the cluster.

After you deploy your Data Grid Server cluster, you create caches through the Data Grid CLI, Data Grid Console, or Hot Rod and REST endpoints. Data Grid Server permanently stores those caches as part of the cluster state that is distributed across nodes. Each joining node receives the complete cluster state that Data Grid Server automatically synchronizes across all nodes as changes occur.

Static configuration

Static configuration is immutable, remaining unchanged at runtime.

You define static configuration when setting up underlying mechanisms such as cluster transport, authentication and encryption, shared datasources, and so on.

By default Data Grid Server uses $RHDG_HOME/server/conf/infinispan.xml for static configuration.

The root element of the configuration is infinispan and declares two base schema:

<infinispan
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="urn:infinispan:config:15.0 https://infinispan.org/schemas/infinispan-config-15.0.xsd
                            urn:infinispan:server:15.0 https://infinispan.org/schemas/infinispan-server-15.0.xsd"
        xmlns="urn:infinispan:config:15.0"
        xmlns:server="urn:infinispan:server:15.0">

Cache container configuration

You use the cache-container element to configure the CacheManager interface that provides mechanisms to manage cache lifecycles:

<!-- Creates a cache manager named "default" that exports statistics. -->
<cache-container name="default"
                 statistics="true">
  <!-- Defines cluster transport properties, including the cluster name. -->
  <!-- Uses the default TCP stack for inter-cluster communication. -->
  <transport cluster="${infinispan.cluster.name}"
             stack="${infinispan.cluster.stack:tcp}"
             node-name="${infinispan.node.name:}"/>
</cache-container>

The cache-container element can also hold the following configuration elements:

Server configuration

You use the server element to configure underlying Data Grid Server mechanisms:

<server>
  <interfaces>
    <interface name="public"> 1
      <inet-address value="${infinispan.bind.address:127.0.0.1}"/> 2
    </interface>
  </interfaces>

  <socket-bindings default-interface="public" 3
                   port-offset="${infinispan.socket.binding.port-offset:0}"> 4
    <socket-binding name="default" 5
                    port="${infinispan.bind.port:11222}"/> 6
    <socket-binding name="memcached" port="11221"/> 7
  </socket-bindings>

  <security>
     <security-realms> 8
        <security-realm name="default"> 9
           <server-identities> 10
              <ssl>
                <keystore path="application.keystore" 11
                          keystore-password="password"
                          alias="server"
                          key-password="password"
                          generate-self-signed-certificate-host="localhost"/>
              </ssl>
           </server-identities>
           <properties-realm groups-attribute="Roles"> 12
              <user-properties path="users.properties" 13
                               relative-to="infinispan.server.config.path"
                               plain-text="true"/> 14
              <group-properties path="groups.properties" 15
                                relative-to="infinispan.server.config.path" />
           </properties-realm>
        </security-realm>
     </security-realms>
  </security>

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

</server>

In previous 7.x versions there was no separate schema for Data Grid Server. This topic lists changes to the Data Grid Server configuration schema between 8.1 and 8.2.

Security authorization

As of Data Grid 8.2, the server configuration enables authorization by default to restrict user access based on roles and permissions.

<cache-container name="default" statistics="true">
  <transport cluster="${infinispan.cluster.name:cluster}"
             stack="${infinispan.cluster.stack:tcp}"
             node-name="${infinispan.node.name:}"/>
  <security>
    <authorization/> 1
  </security>
</cache-container>

Client trust stores

As of Data Grid 8.2, you can add client trust stores to the server identity configuration and use the truststore-realm element to verify certificates.

<security-realm name="default">
   <server-identities>
      <ssl>
         <keystore path="server.pfx"
                   keystore-password="password" alias="server"/>
      </ssl>
   </server-identities>
   <truststore-realm path="trust.pfx" password="secret"/>
</security-realm>

<security-realm name="default">
   <server-identities>
      <ssl>
         <keystore path="server.pfx"
                   keystore-password="password" alias="server"/>
         <truststore path="trust.pfx" password="secret"/> 1
      </ssl>
   </server-identities>
   <truststore-realm/> 2
</security-realm>

Endpoint connectors

As of Data Grid 8.2, the hotrod-connector and rest-connector elements are implicitly set in the default endpoints configuration.

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

Modified elements and attributes

New elements and attributes

Deprecated elements and attributes

The following elements and attributes are now deprecated:

Removed elements and attributes

No elements or attributes are removed in Data Grid 8.2.

This topic lists changes to the Data Grid Server configuration schema between 8.2 and 8.3.

Schema changes

<endpoints socket-binding="default" security-realm="default">
  <hotrod-connector name="hotrod"/>
  <rest-connector name="rest"/>
</endpoints>

<endpoints>
  <endpoint socket-binding="public" security-realm="application-realm" admin="false">
    <hotrod-connector/>
    <rest-connector/>
  </endpoint>
  <endpoint socket-binding="private" security-realm="management-realm">
    <hotrod-connector/>
    <rest-connector/>
  </endpoint>
</endpoints>

Modified elements and attributes

No elements or attributes are modified in Data Grid 8.3.

New elements and attributes

Deprecated elements and attributes

The following elements and attributes are now deprecated:

Removed elements and attributes

No elements or attributes are removed in Data Grid 8.3.

This topic lists changes to the Data Grid Server configuration schema between 8.3 and 8.4.

Schema changes

No schema changes were made in Data Grid 8.4.

Modified elements and attributes

The following attributes for configuring a data source connection pool have now default values:

The following attributes for configuring a data source connection pool have default value set to 0, which means that these features are disabled.

New elements and attributes

Deprecated elements and attributes

No elements and attributes were deprecated in Data Grid 8.4.

Removed elements and attributes

This topic lists changes to the Data Grid Server configuration schema between 8.4 and 8.5.

Modified elements and attributes

New elements and attributes

Deprecated elements and attributes

No elements and attributes were deprecated in Data Grid 8.5.

Removed elements and attributes

No elements and attributes were removed in Data Grid 8.5.

This section describes Data Grid Server endpoint and network configuration when migrating from previous versions.

Data Grid 8 simplifies server endpoint configuration by using a single network interface and port to expose endpoints on the network.

<interfaces>
  <interface name="management">
    <inet-address value="${jboss.bind.address.management:127.0.0.1}"/>
  </interface>
  <interface name="public">
    <inet-address value="${jboss.bind.address:127.0.0.1}"/>
  </interface>
</interfaces>

<interfaces>
  <interface name="public">
    <inet-address value="${infinispan.bind.address:127.0.0.1}"/>
  </interface>
</interfaces>

<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
  <socket-binding name="management-http" interface="management" port="${jboss.management.http.port:9990}"/>
  <socket-binding name="management-https" interface="management" port="${jboss.management.https.port:9993}"/>
  <socket-binding name="hotrod" port="11222"/>
  <socket-binding name="hotrod-internal" port="11223"/>
  <socket-binding name="hotrod-multi-tenancy" port="11224"/>
  <socket-binding name="memcached" port="11211"/>
  <socket-binding name="rest" port="8080"/>
  ...
</socket-binding-group>

<socket-bindings default-interface="public"
                 port-offset="${infinispan.socket.binding.port-offset:0}">
  <socket-binding name="default" port="${infinispan.bind.port:11222}"/>
  <socket-binding name="memcached" port="11221"/>
</socket-bindings>

<subsystem xmlns="urn:infinispan:server:endpoint:9.4">
  <hotrod-connector socket-binding="hotrod" cache-container="local">
    <topology-state-transfer lazy-retrieval="false" lock-timeout="1000" replication-timeout="5000"/>
  </hotrod-connector>
  <rest-connector socket-binding="rest" cache-container="local">
    <authentication security-realm="ApplicationRealm" auth-method="BASIC"/>
  </rest-connector>
</subsystem>

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

<endpoints socket-binding="default" security-realm="default">
  <hotrod-connector name="hotrod"/>
  <rest-connector name="rest"/>
</endpoints>

<endpoints>
  <endpoint socket-binding="public" security-realm="application-realm" admin="false">
    <hotrod-connector/>
    <rest-connector/>
  </endpoint>
  <endpoint socket-binding="private" security-realm="management-realm">
    <hotrod-connector/>
    <rest-connector/>
  </endpoint>
</endpoints>

Data Grid Server security configures authentication and encryption to prevent network attack and safeguard data.

<security>
  <security-realms>
    ...
  </security-realms>
</security>

<security-realm name="default">
  <server-identities>
    <ssl>
      <keystore path="..."
                relative-to="..."
                keystore-password="..."
                alias="..."
                key-password="..."
                generate-self-signed-certificate-host="..."/>
    </ssl>
  </server-identities>
  ...
<security-realm>

<hotrod-connector name="hotrod">
  <authentication>
    <sasl mechanisms="..." server-name="..."/>
  </authentication>
</hotrod-connector>
<rest-connector name="rest">
  <authentication>
    <mechanisms="..." server-principal="..."/>
  </authentication>
</rest-connector>

<authorization audit-logger="org.infinispan.security.impl.DefaultAuditLogger">

When migrating from previous versions, you can create different network locations for Data Grid endpoints to match your existing configuration. However, because Data Grid architecture has changed and now uses a single port for all client connections, not all options in previous versions are available.

Data Grid 7.x JDBC cache stores can use a PooledConnectionFactory to obtain database connections.

Data Grid 8 lets you create managed datasources in the server configuration to optimize connection pooling and performance for database connections with JDBC cache stores.

Datasource configurations are composed of two sections:

You first define the datasource connection factory and connection pool in the server configuration and then add it to your JDBC cache store configuration.

For more information on migrating JDBC cache stores, see the Migrating Cache Stores section in this document.

Data Grid 8 exposes metrics via both JMX and a /metrics endpoint for integration with metrics tooling such as Prometheus.

The /metrics endpoint provides:

In previous versions, Prometheus metrics were collected by an agent that mapped JMX metrics instead of being supported natively.

Previous versions of Data Grid also used the JBoss Operations Network (JON) plug-in to obtain metrics and perform operations. Data Grid 8 no longer uses the JON plug-in.

Data Grid 8 separates JMX and Prometheus metrics into cache manager and cache level configurations.

<cache-container name="default"
                 statistics="true"> 1
  <jmx enabled="true" /> 2
</cache-container>

<distributed-cache name="mycache" statistics="true" /> 1

Use the following commands and examples as a quick reference for working with Data Grid Server.

Starting server instances

Starting the CLI

Creating users

Stopping server instances

Listing available command options

Use the -h flag to list available command options for running servers.

7.x to 8 reference