Chapter 3. Migrating Data Grid configuration

Find changes to Data Grid configuration that affect migration to Data Grid 8.

3.1. Data Grid cache configuration

Data Grid 8 provides empty cache containers by default. When you start Data Grid, it instantiates a cache manager so you can create caches at runtime.

However, in comparison with previous versions, there is no "default" cache out of the box.

In Data Grid 8, caches that you create through the CacheContainerAdmin API are permanent to ensure that they survive cluster restarts.

Permanent caches

.administration()
   .withFlags(AdminFlag.PERMANENT) 1
   .getOrCreateCache("myPermanentCache", "org.infinispan.DIST_SYNC");

1: AdminFlag.PERMANENT is enabled by default to ensure that caches survive restarts.

You do not need to set this flag when you create caches. However, you must separately add persistent storage to Data Grid for data to survive restarts, for example:

ConfigurationBuilder b = new ConfigurationBuilder();
b.persistence()
   .addSingleFileStore()
   .location("/tmp/myDataStore")
   .maxEntries(5000);

Volatile caches

.administration()
   .withFlags(AdminFlag.VOLATILE) 1
   .getOrCreateCache("myTemporaryCache", "org.infinispan.DIST_SYNC"); 2

1: Sets the VOLATILE flag so caches are lost when Data Grid restarts.
2: Returns a cache named "myTemporaryCache" or creates one using the DIST_SYNC template.

Data Grid 8 provides cache templates for server installations that you can use to create caches with recommended settings.

You can get a list of available cache templates as follows:

Use Tab auto-completion with the CLI:

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

Use the REST API:

GET 127.0.0.1:11222/rest/v2/cache-managers/default/cache-configs/templates

3.1.1. Cache encoding

When you create remote caches you should configure the MediaType for keys and values. Configuring the MediaType guarantees the storage format for your data.

To encode caches, you specify the MediaType in your configuration. Unless you have others requirements, you should use ProtoStream, which stores your data in a language-neutral, backwards compatible format.

<encoding media-type="application/x-protostream"/>

Distributed cache configuration with encoding

<infinispan>
    <cache-container>
        <distributed-cache name="myCache" mode="SYNC">
          <encoding media-type="application/x-protostream"/>
           ...
        </distributed-cache>
    </cache-container>
</infinispan>

If you do not encode remote caches, Data Grid Server logs the following message:

WARN  (main) [org.infinispan.encoding.impl.StorageConfigurationManager] ISPN000599: Configuration for cache 'mycache' does not define the encoding for keys or values. If you use operations that require data conversion or queries, you should configure the cache with a specific MediaType for keys or values.

In a future version, cache encoding will be required for operations where data conversion takes place; for example, cache indexing and searching the data container, remote task execution, reading and writing data in different formats from the Hot Rod and REST endpoints, as well as using remote filters, converters, and listeners.

3.1.2. Cache health status

Data Grid 7.x includes a Health Check API that returns health status of the cluster as well as caches within it.

Data Grid 8 also provides a Health API. For embedded and server installations, you can access the Health API via JMX with the following MBean:

org.infinispan:type=CacheManager,name="default",component=CacheContainerHealth

Data Grid Server also exposes the Health API through the REST endpoint and the Data Grid Console.

Table 3.1. Health Status
7.x	8.x	Description
`HEALTHY`	`HEALTHY`	Indicates a cache is operating as expected.
`Rebalancing`	`HEALTHY_REBALANCING`	Indicates a cache is in the rebalancing state but otherwise operating as expected.
`Unhealthy`	`DEGRADED`	Indicates a cache is not operating as expected and possibly requires troubleshooting.
N/A	`FAILED`	Added in 8.2 to indicate that a cache could not start with the supplied configuration.

Additional resources

Configuring Data Grid Caches

3.1.3. Changes to the Data Grid 8.1 configuration schema

This topic lists changes to the Data Grid configuration schema between 8.0 and 8.1.

New and modified elements and attributes

stack adds support for inline JGroups stack definitions.
stack.combine and stack.position attributes let you override and modify JGroups stack definitions.
metrics lets you configure how Data Grid exports metrics that are compatible with the Eclipse MicroProfile Metrics API.
context-initializer lets you specify a SerializationContextInitializer implementation that initializes a Protostream-based marshaller for user types.
key-transformers lets you register transformers that convert custom keys to String for indexing with Lucene.
statistics now defaults to "false".

Deprecated elements and attributes

The following elements and attributes are now deprecated:

address-count attribute for the off-heap element.
protocol attribute for the transaction element.
duplicate-domains attribute for the jmx element.
advanced-externalizer
custom-interceptors
state-transfer-executor
transaction-protocol

Removed elements and attributes

The following elements and attributes were deprecated in a previous release and are now removed:

deadlock-detection-spin
compatibility
write-skew
versioning
data-container
eviction
eviction-thread-policy

3.1.4. Changes to the Data Grid 8.2 configuration schema

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

Modified elements and attributes

white-list changes to allow-list
role is now a sub-element of roles for defined user roles and permissions for security authorization.
context-initializer is updated for automatic SerializationContextInitializer registration.
If your configuration does not contain context-initializer elements then the java.util.ServiceLoader mechanism automatically discovers all SerializationContextInitializer implementations on the classpath and loads them.
Default value of the minOccurs attribute changes from 0 to 1 for the indexed-entity element.

New elements and attributes

property attribute added to the transport element that lets you pass name/value transport properties.
cache-size and cache-timeout attributes added to the security element to configure the size and timeout for the Access Control List (ACL) cache.
index-reader, index-writer, and index-merge child elements added to the indexing element.
storage attribute added to the indexing element that specifies index storage options.
path attribute added to the indexing element that specifies a directory when using file system storage for the index.
bias-acquisition attribute added to the scattered-cache element that controls when nodes can acquire a bias on an entry.
bias-lifespan attribute added to the scattered-cache element that specifies, in milliseconds, how long nodes can keep an acquired bias.
merge-policy attribute added to the backups element that specifies an algorithm for resolving conflicts with cross-site replication.
mode attribute added to the state-transfer child element for the backup.
The mode attribute configures whether cross-site replication state transfer happens manually or automatically.
INSERT_ABOVE, INSERT_BEFORE, and INSERT_BELOW attributes added to the stack.combine attribute for extending JGroups stacks with inheritance.

Deprecated elements and attributes

No elements or attributes are deprecated in Data Grid 8.2.

Removed elements and attributes

No elements or attributes are removed in Data Grid 8.2.

3.1.5. Changes to the Data Grid 8.3 configuration schema

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

Schema changes

urn:infinispan:config:store:soft-index namespace is no longer available.

Modified elements and attributes

file-store element in the urn:infinispan:config namespace defaults to using soft-index file cache stores.
single-file-store element is included in the urn:infinispan:config namespace but is now deprecated.

New elements and attributes

index and data elements are now available to configure how Data Grid stores indexes and data for file-based cache stores with the file-store element.
open-files-limit and compaction-threshold attributes for the file-store element.
cluster attribute added to the remote-sites and remote-site elements that lets you define global cluster names for cross-site communication.
Note
Global cluster names that you specify with the cluster attribute must be the same at all sites.
accurate-size attribute added to the metrics element to enable calculations of the data set with the currentNumberOfEntries statistic.
Important
As of Data Grid 8.3 the currentNumberOfEntries statistic returns a value of -1 by default because it is an expensive operation to perform.
touch attribute added to the expiration element that controls how timestamps get updated for entries in clustered caches with maximum idle expiration. The default value is SYNC and the attribute applies only to caches that use synchronous replication. Timestamps are updated asynchronously for caches that use asynchronous replication.
lifespan attribute added to the strong-counter for attaching expiration values, in milliseconds. The default value is -1 which means strong consistent counters never expire.
Note
The lifespan attribute for strong counters is currently available as a Technology Preview.

Deprecated elements and attributes

The following elements and attributes are now deprecated:

single-file-store element.
max-entries and path attributes for the file-store element.

Removed elements and attributes

The following elements and attributes are no longer available in the Data Grid schema:

remote-command-executor attribute for the transport element.
capacity attribute for the distributed-cache element.

3.1.6. Changes to the Data Grid 8.4 configuration schema

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

Schema changes

New elements and attributes

default-max-results attribute added to the query element that lets you limits the number of results returned by a query. Applies to indexed, non-indexed, and hybrid queries.
startup-mode attribute that lets you define which operation should Data Grid perform when the cache starts. The options are purge, reindex, auto or none. The default value is none.
raft-members attribute that lets you define a list of raft members separated by space.

Deprecated elements and attributes

The following elements and attributes are now deprecated:

scattered-cache element is now deprecated

Removed elements and attributes

The following elements and attributes are no longer available in the Data Grid schema:

fetch-state store property is no longer available. You can remove the attribute from your xml configuration.

3.1.7. Changes to the Data Grid 8.5 configuration schema

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

New elements and attributes

tracing element added to cache-container that lets you configure tracing and the traces can be collected by an OpenTelemetry collector.
group-only-mapping attribute added to authorization. Use this attribute to specify whether principal-to-role mapping applies only to group principals or also to user principals. The default value true applies principal-to-role mapping only to group principals. Set the value to false to apply the mapping to both the principal types.
description attribute added to roles that lets you defines the description of the role.
schema-compatibility attribute added to serialization that lets you specify the compatibility validation that is performed when updating schemas.
unclean-shutdown-action attribute added to global-state that lets you define the action taken when a dangling lock file is found in the persistent global state, signifying an unclean shutdown of the node. The default value is FAIL.
index-sharding element added to indexing. Sharding is the process of splitting index data into multiple smaller indexes called shards. Sharding improves performance when dealing with large amounts of data. Sharding is disabled by default.
indexing-mode element added to indexing that lets you define how cache operations are propagated to the indexes. By default, all the changes to the cache are immediately applied to the indexes.
tracing element added to indexing that lets you configure tracing and the traces can be collected by an OpenTelemetry collector.
aliases attribute added to cache that lets you define zero or more alias names for a cache.
statistics attribute added to cache that defines whether the cache should collect statistics. Keep statistics collection disabled for optimal performance.

Deprecated elements and attributes

There are no deprecations in this release.

Removed elements and attributes

The following elements and attributes are no longer available in the Data Grid schema:

scattered-cache element has been removed.
property element has been removed from cache.
auto-config element has been removed from indexing.
statistics-available attribute has been removed from indexing.
connection-interval attribute as been removed from persistence.

3.2. Eviction configuration

Data Grid 8 simplifies eviction configuration in comparison with previous versions. However, eviction configuration has undergone numerous changes across different Data Grid versions, which means migration might not be straightforward.

Note

As of Data Grid 7.2, the memory element replaces the eviction element in the configuration. This section refers to eviction configuration with the memory element only. For information on migrating configuration that uses the eviction element, refer to the Data Grid 7.2 documentation.

3.2.1. Storage types

Data Grid lets you control how to store entries in memory, with the following options:

Store objects in JVM heap memory.
Store bytes in native memory (off-heap).
Store bytes in JVM heap memory.

Changes in Data Grid 8

In previous 7.x versions, and 8.0, you use object, binary, and off-heap elements to configure the storage type.

Starting with Data Grid 8.1, you use a storage attribute to store objects in JVM heap memory or as bytes in off-heap memory.

To store bytes in JVM heap memory, you use the encoding element to specify a binary storage format for your data.

Data Grid 7.x	Data Grid 8
`<memory><object /></memory>`	`<memory />`
`<memory><off-heap /></memory>`	`<memory storage="OFF_HEAP" />`
`<memory><binary /></memory>`	`<encoding media-type="…" />`

Object storage in Data Grid 8

By default, Data Grid 8.1 uses object storage (JVM heap):

<distributed-cache>
   <memory />
</distributed-cache>

You can also configure storage="HEAP" explicitly to store data as objects in JVM heap memory:

<distributed-cache>
   <memory storage="HEAP" />
</distributed-cache>

Off-heap storage in Data Grid 8

Set "OFF_HEAP" as the value of the storage attribute to store data as bytes in native memory:

<distributed-cache>
   <memory storage="OFF_HEAP" />
</distributed-cache>

Off-heap address count

In previous versions, the address-count attribute for offheap lets you specify the number of pointers that are available in the hash map to avoid collisions. With Data Grid 8.1, address-count is no longer used and off-heap memory is dynamically re-sized to avoid collisions.

Binary storage in Data Grid 8

Specify a binary storage format for cache entries with the encoding element:

<distributed-cache>
   <!--Configure MediaType for entries with binary formats.-->
   <encoding media-type="application/x-protostream"/>
   <memory ... />
</distributed-cache>

Note

As a result of this change, Data Grid no longer stores primitives and String mixed with byte[], but stores only byte[].

3.2.2. Eviction threshold

Eviction lets Data Grid control the size of the data container by removing entries when the container becomes larger than a configured threshold.

In Data Grid 7.x and 8.0, you specify two eviction types that define the maximum limit for entries in the cache:

COUNT measures the number of entries in the cache.
MEMORY measures the amount of memory that all entries in the cache take up.

Depending on the configuration you set, when either the count or the total amount of memory exceeds the maximum, Data Grid removes unused entries.

Data Grid 7.x and 8.0 also use the size attribute that defines the size of the data container as a long. Depending on the storage type you configure, eviction occurs either when the number of entries or amount of memory exceeds the value of the size attribute.

With Data Grid 8.1, the size attribute is deprecated along with COUNT and MEMORY. Instead, you configure the maximum size of the data container in one of two ways:

Total number of entries with the max-count attribute.
Maximum amount of memory, in bytes, with the max-size attribute.

Eviction based on total number of entries

<distributed-cache>
   <memory max-count="..." />
</distributed-cache>

Eviction based on maximum amount of memory

<distributed-cache>
   <memory max-size="..." />
</distributed-cache>

3.2.3. Eviction strategies

Eviction strategies control how Data Grid performs eviction.

Data Grid 7.x and 8.0 let you set one of the following eviction strategies with the strategy attribute:

Strategy	Description
`NONE`	Data Grid does not evict entries. This is the default setting unless you configure eviction.
`REMOVE`	Data Grid removes entries from memory so that the cache does not exceed the configured size. This is the default setting when you configure eviction.
`MANUAL`	Data Grid does not perform eviction. Eviction takes place manually by invoking the `evict()` method from the `Cache` API.
`EXCEPTION`	Data Grid does not write new entries to the cache if doing so would exceed the configured size. Instead of writing new entries to the cache, Data Grid throws a `ContainerFullException`.

With Data Grid 8.1, you can use the same strategies as in previous versions. However, the strategy attribute is replaced with the when-full attribute.

<distributed-cache>
   <memory when-full="<eviction_strategy>" />
</distributed-cache>

Eviction algorithms

With Data Grid 7.2, the ability to configure eviction algorithms was deprecated along with the Low Inter-Reference Recency Set (LIRS).

From version 7.2 onwards, Data Grid includes the Caffeine caching library that implements a variation of the Least Frequently Used (LFU) cache replacement algorithm known as TinyLFU. For off-heap storage, Data Grid uses a custom implementation of the Least Recently Used (LRU) algorithm.

3.2.4. Eviction configuration comparison

Compare eviction configuration between different Data Grid versions.

Object storage and evict on number of entries

7.2 to 8.0

<memory>
  <object size="1000000" eviction="COUNT" strategy="REMOVE"/>
</memory>

8.1

<memory max-count="1MB" when-full="REMOVE"/>

Object storage and evict on amount of memory

7.2 to 8.0

<memory>
  <object size="1000000" eviction="MEMORY" strategy="MANUAL"/>
</memory>

8.1

<memory max-size="1MB" when-full="MANUAL"/>

Binary storage and evict on number of entries

7.2 to 8.0

<memory>
  <binary size="500000000" eviction="MEMORY" strategy="EXCEPTION"/>
</memory>

8.1

<cache>
   <encoding media-type="application/x-protostream"/>
   <memory max-size="500 MB" when-full="EXCEPTION"/>
</cache>

Binary storage and evict on amount of memory

7.2 to 8.0

<memory>
  <binary size="500000000" eviction="COUNT" strategy="MANUAL"/>
</memory>

8.1

<memory max-count="500 MB" when-full="MANUAL"/>

Off-heap storage and evict on number of entries

7.2 to 8.0

<memory>
  <off-heap size="10000000" eviction="COUNT"/>
</memory>

8.1

<memory storage="OFF_HEAP" max-count="10MB"/>

Off-heap storage and evict on amount of memory

7.2 to 8.0

<memory>
  <off-heap size="1000000000" eviction="MEMORY"/>
</memory>

8.1

<memory storage="OFF_HEAP" max-size="1GB"/>

Additional resources

Configuring Data Grid caches
New eviction policy TinyLFU since RHDG 7.3 (Red Hat Knowledgebase)
Product Documentation for Data Grid 7.2

3.3. Expiration configuration

Expiration removes entries from caches based on their lifespan or maximum idle time.

When migrating your configuration from Data Grid 7.x to 8, there are no changes that you need to make for expiration. The configuration remains the same:

Lifespan expiration

<expiration lifespan="1000" />

Max-idle expiration

<expiration max-idle="1000" interval="120000" />

For Data Grid 7.2 and earlier, using max-idle with clustered caches had technical limitations that resulted in performance degradation.

As of Data Grid 7.3, Data Grid sends touch commands to all owners in clustered caches when client read entries that have max-idle expiration values. This ensures that the entries have the same relative access time across the cluster.

Data Grid 8 sends the same touch commands for max-idle expiration across clusters. However there are some technical considerations you should take into account before you start using max-idle. Refer to Configuring Data Grid caches to read more about how expiration works and to review how the touch commands affect performance with clustered caches.

Additional resources

Configuring Data Grid caches

3.4. Persistent cache stores

In comparison with Data Grid 7.x, there are some changes to cache store configuration in Data Grid 8.

Persistence SPI

Data Grid 8.1 introduces the NonBlockingStore interface for cache stores. The NonBlockingStore SPI exposes methods that must never block the invoking thread.

Cache stores that connect Data Grid to persistent data sources implement the NonBlockingStore interface.

For custom cache store implementations that use blocking operations, Data Grid provides a BlockingManager utility class to handle those operations.

The introduction of the NonBlockingStore interface deprecates the following interfaces:

CacheLoader
CacheWriter
AdvancedCacheLoader
AdvancedCacheWriter

Custom cache stores

Data Grid 8 lets you configure custom cache stores with the store element as in previous versions.

The following changes apply:

The singleton attribute is removed. Use shared=true instead.
The segmented attribute is added and defaults to true.

Segmented cache stores

As of Data Grid 8, cache store configuration defaults to segmented="true" and applies to the following cache store elements:

store
file-store
string-keyed-jdbc-store
jpa-store
remote-store
rocksdb-store
soft-index-file-store

Note

As of Data Grid 8.3, file-store element in cache configuration creates a soft index file-based store. For more information see File-based cache stores default to soft index.

Single file cache stores

The relative-to attribute for Single File cache stores is removed in Data Grid 8. If your cache store configuration includes this attribute, Data Grid ignores it and uses only the path attribute to configure store location.

JDBC cache stores

JDBC cache stores must include an xlmns namespace declaration, which was not required in some Data Grid 7.x versions.

<persistence>
  <string-keyed-jdbc-store xmlns="urn:infinispan:config:store:jdbc:14.0" shared="true">
   ...
</persistence>

JDBC connection factories

Data Grid 7.x JDBC cache stores can use the following ConnectionFactory implementations to obtain a database connection:

ManagedConnectionFactory
SimpleConnectionFactory
PooledConnectionFactory

Data Grid 8 now use connections factories based on Agroal, which is the same as Red Hat JBoss EAP, to connect to databases. It is no longer possible to use c3p0.properties and hikari.properties files.

Note

As of Data Grid 8.3 JDBC connection factories are part of the org.infinispan.persistence.jdbc.common.configuration package.

Segmentation

JDBC String-Based cache store configuration that enables segmentation, which is now the default, must include the segmentColumnName and segmentColumnType parameters, as in the following programmatic examples:

MySQL Example

builder.table()
       .tableNamePrefix("ISPN")
       .idColumnName("ID_COLUMN").idColumnType(“VARCHAR(255)”)
       .dataColumnName("DATA_COLUMN").dataColumnType(“VARBINARY(1000)”)
       .timestampColumnName("TIMESTAMP_COLUMN").timestampColumnType(“BIGINT”)
       .segmentColumnName("SEGMENT_COLUMN").segmentColumnType("INTEGER")

PostgreSQL Example

builder.table()
       .tableNamePrefix("ISPN")
       .idColumnName("ID_COLUMN").idColumnType(“VARCHAR(255)”)
       .dataColumnName("DATA_COLUMN").dataColumnType(“BYTEA”)
       .timestampColumnName("TIMESTAMP_COLUMN").timestampColumnType("BIGINT”)
       .segmentColumnName("SEGMENT_COLUMN").segmentColumnType("INTEGER");

Write-behind

The thread-pool-size attribute for Write-Behind mode is removed in Data Grid 8.

Removed cache stores and loaders

Data Grid 7.3 deprecates the following cache stores and loaders that are no longer available in Data Grid 8:

Cassandra Cache Store
REST Cache Store
LevelDB Cache Store
CLI Cache Loader

Cache store migrator

Cache stores in previous versions of Data Grid store data in a binary format that is not compatible with Data Grid 8.

Use the StoreMigrator utility to migrate data in persistent cache stores to Data Grid 8.

3.4.1. File-based cache stores default to soft index

Including file-store persistence in cache configuration now creates a soft index file-based cache store, SoftIndexFileStore, instead of a single-file cache store, SingleFileStore. In Data Grid 8.2 and earlier, SingleFileStore was the default for file-based cache stores.

If you are migrating or upgrading to Data Grid 8.3, any file-store configuration is automatically converted to a SoftIndexFileStore at server startup. When your configuration is converted to SoftIndexFileStore, it is not possible to revert back to SingleFileStore without modifying the configuration to ensure compatibility with the new store.

3.4.1.1. Declarative configuration

Data Grid 8.2 and earlier

<persistence>
  <soft-index-file-store xmlns="urn:infinispan:config:soft-index:12.1">
    <index path="testCache/index" />
    <data path="testCache/data" />
  </soft-index-file-store>
</persistence>

Data Grid 8.3 and later

<persistence>
  <file-store>
    <index path="testCache/index" />
    <data path="testCache/data" />
  </file-store>
</persistence>

3.4.1.2. Programmatic configuration

Data Grid 8.2 and earlier

ConfigurationBuilder b = new ConfigurationBuilder();
b.persistence()
    .addStore(SoftIndexFileStoreConfigurationBuilder.class)
        .indexLocation("testCache/index");
        .dataLocation("testCache/data")

Data Grid 8.3 and later

ConfigurationBuilder b = new ConfigurationBuilder();
b.persistence()
    .addSoftIndexFileStore()
        .indexLocation("testCache/index")
        .dataLocation("testCache/data");

3.4.1.3. Using single file cache stores with Data Grid 8.3

You can configure SingleFileStore cache stores with Data Grid 8.3 or later but Red Hat does not recommend doing so. You should use SoftIndexFileStore cache stores because they offer better scalability.

Declarative

<persistence passivation="false">
  <single-file-store shared="false"
                     preload="true"
                     fetch-state="true"
                     read-only="false"/>
</persistence>

Programmatic

ConfigurationBuilder b = new ConfigurationBuilder();
b.persistence()
    .addSingleFileStore();

3.5. Data Grid cluster transport

Data Grid uses JGroups technology to handle communication between clustered nodes.

JGroups stack configuration elements and attributes have not significantly changed from previous Data Grid versions.

As in previous versions, Data Grid provides preconfigured JGroups stacks that you can use as a starting point for building custom cluster transport configuration optimized for your network requirements. Likewise, Data Grid provides the ability to add JGroups stacks defined in external XML files to your infinispan.xml.

Data Grid 8 has brought usability improvements to make cluster transport configuration easier:

Inline stacks let you configure JGroups stacks directly within infinispan.xml using the jgroups element.
Declare JGroups schemas within infinispan.xml .
Preconfigured JGroups stacks for UDP and TCP protocols.
Inheritance attributes that let you extend JGroups stacks to adjust specific protocols and properties.

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

   <jgroups> 2
      <stack name="xsite" extends="udp"> 3
         <relay.RELAY2 site="LON" xmlns="urn:org:jgroups"/>
         <remote-sites default-stack="tcp">
            <remote-site name="LON"/>
            <remote-site name="NYC"/>
         </remote-sites>
      </stack>
   </jgroups>

   <cache-container ...>
   ...
</infinispan>

1: Declares the JGroups 4.2 schema within infinispan.xml.
2: Adds a JGroups element to contain custom stack definitions.
3: Defines a JGroups protocol stack for cross-site replication.

3.5.1. Transport security

As in previous versions, Data Grid 8 uses the JGroups SYM_ENCRYPT and ASYM_ENCRYPT protocols to encrypt cluster communication.

As of Data Grid you can also use a security realm that includes a keystore and trust store as a TLS server identity to secure cluster transport, for example:

<cache-container>
  <transport server:security-realm="tls-transport"/>
</cache-container>

Node authentication

In Data Grid 7.x, the JGroups SASL protocol enables nodes to authenticate against security realms in both embedded and remote server installations.

As of Data Grid 8, it is not possible to configure node authentication against security realms. Likewise Data Grid 8 does not recommend using the JGroups AUTH protocol for authenticating clustered nodes.

However, with embedded Data Grid installations, JGroups cluster transport includes a SASL configuration as part of the jgroups element. As in previous versions, the SASL configuration relies on JAAS notions, such as CallbackHandlers, to obtain certain information necessary for node authentication.

3.5.2. Retransmission requests

Data Grid 8.2 changes the configuration for retransmission requests for the UNICAST3 and NAKACK2 protocols in the default JGroups stacks, as follows:

The value of the xmit_interval property is increased from 100 milliseconds to 200 milliseconds.
The max_xmit_req_size property now sets a maximum of 500 messages per re-transmission request, instead of a maximum of 8500 with UDP or 64000 with TCP.

As part of your migration to Data Grid 8 you should adapt any custom JGroups stack configuration to use these recommended settings.

Additional resources

3.6. Data Grid authorization

Data Grid uses role-based access control (RBAC) to restrict access to data and cluster encryption to secure communication between nodes.

Roles and Permissions

Data Grid 8.2 provides a set of default users and permissions that you can use for RBAC, with the following changes:

ClusterRoleMapper is the default mechanism that Data Grid uses to associate security principals to authorization roles.
A new MONITOR permission allows user access to Data Grid statistics.
A new CREATE permission that users need to create and delete resources such as caches and counters.
Note
CREATE replaces the ___schema_manager and \___script_manager roles that users required to create and remove Protobuf schema and server scripts in Data Grid 8.1 and earlier.
When migrating to Data Grid 8.2, you should assign the deployer role to users who had the ___schema_manager and \___script_manager roles in Data Grid 8.1 or earlier. Use the command line interface (CLI) as follows:
```
[//containers/default]> user roles grant --roles=deployer <user>
```

cache manager permissions

Table 3.2. Data Grid 8.1
Permission	Function	Description
CONFIGURATION	`defineConfiguration`	Defines new cache configurations.
LISTEN	`addListener`	Registers listeners against a cache manager.
LIFECYCLE	`stop`	Stops the cache manager.
ALL	-	Includes all cache manager permissions.

Table 3.3. Data Grid 8.2
Permission	Function	Description
CONFIGURATION	`defineConfiguration`	Defines new cache configurations.
LISTEN	`addListener`	Registers listeners against a cache manager.
LIFECYCLE	`stop`	Stops the cache manager.
CREATE	`createCache`, `removeCache`	Create and remove container resources such as caches, counters, schemas, and scripts.
MONITOR	`getStats`	Allows access to JMX statistics and the `metrics` endpoint.
ALL	-	Includes all cache manager permissions.

Cache permissions

Table 3.4. Data Grid 8.1
Permission	Function	Description
`READ`	`get`, `contains`	Retrieves entries from a cache.
WRITE	`put`, `putIfAbsent`, `replace`, `remove`, `evict`	Writes, replaces, removes, evicts data in a cache.
EXEC	`distexec`, `streams`	Allows code execution against a cache.
LISTEN	`addListener`	Registers listeners against a cache.
BULK_READ	`keySet`, `values`, `entrySet`, `query`	Executes bulk retrieve operations.
BULK_WRITE	`clear`, `putAll`	Executes bulk write operations.
LIFECYCLE	`start`, `stop`	Starts and stops a cache.
ADMIN	`getVersion`, `addInterceptor*`, `removeInterceptor`, `getInterceptorChain`, `getEvictionManager`, `getComponentRegistry`, `getDistributionManager`, `getAuthorizationManager`, `evict`, `getRpcManager`, `getCacheConfiguration`, `getCacheManager`, `getInvocationContextContainer`, `setAvailability`, `getDataContainer`, `getStats`, `getXAResource`	Allows access to underlying components and internal structures.
ALL	-	Includes all cache permissions.
ALL_READ	-	Combines the READ and BULK_READ permissions.
ALL_WRITE	-	Combines the WRITE and BULK_WRITE permissions.

Table 3.5. Data Grid 8.2
Permission	Function	Description
READ	`get`, `contains`	Retrieves entries from a cache.
WRITE	`put`, `putIfAbsent`, `replace`, `remove`, `evict`	Writes, replaces, removes, evicts data in a cache.
EXEC	`distexec`, `streams`	Allows code execution against a cache.
LISTEN	`addListener`	Registers listeners against a cache.
BULK_READ	`keySet`, `values`, `entrySet`, `query`	Executes bulk retrieve operations.
BULK_WRITE	`clear`, `putAll`	Executes bulk write operations.
LIFECYCLE	`start`, `stop`	Starts and stops a cache.
ADMIN	`getVersion`, `addInterceptor*`, `removeInterceptor`, `getInterceptorChain`, `getEvictionManager`, `getComponentRegistry`, `getDistributionManager`, `getAuthorizationManager`, `evict`, `getRpcManager`, `getCacheConfiguration`, `getCacheManager`, `getInvocationContextContainer`, `setAvailability`, `getDataContainer`, `getStats`, `getXAResource`	Allows access to underlying components and internal structures.
MONITOR	`getStats`	Allows access to JMX statistics and the `metrics` endpoint.
ALL	-	Includes all cache permissions.
ALL_READ	-	Combines the READ and BULK_READ permissions.
ALL_WRITE	-	Combines the WRITE and BULK_WRITE permissions.

Cache manager authorization

As of Data Grid 8.2, you can include the authorization element in the cache-container security configuration as follows:

<infinispan>
  <cache-container name="secured">
    <security>
      <authorization/> 1
    </security>
  </cache-container>
</infinispan>

1: Enables security authorization for the cache manager with default roles and permissions.

You can also define global authorization configuration as follows:

<infinispan>
  <cache-container default-cache="secured" name="secured">
    <security>
      <authorization> 1
        <identity-role-mapper /> 2
        <role name="admin" permissions="ALL" /> 3
        <role name="reader" permissions="READ" />
        <role name="writer" permissions="WRITE" />
        <role name="supervisor" permissions="READ WRITE EXEC"/>
      </authorization>
    </security>
  </cache-container>
</infinispan>

1: Requires user permission to control the cache manager lifecycle.
2: Specifies an implementation of PrincipalRoleMapper that maps Principals to roles.
3: Defines a set of roles and associated permissions.

Implicit cache authorization

Data Grid 8 improves usability by allowing caches to inherit authorization configuration from the cache-container so you do not need to explicitly configure roles and permissions for each cache.

<local-cache name="secured">
  <security>
    <authorization/> 1
  </security>
</local-cache>

1: Uses roles and permissions defined in the cache container.
As of Data Grid 8.2, including the authorization element in the configuration uses the default roles and permissions to restrict access to that cache unless you define a set of custom global permissions.

Additional resources

Data Grid Security Guide