Chapter 1. Getting started with Data Grid Server

The Data Grid Server container image is available at the following registries:

Start an instance of Infinispan Server by executing the following command:

docker run -p 11222:11222 --name infinispan infinispan/server

podman run -p 11222:11222 --net=host --name infinispan infinispan/server

By default, the image has authentication enabled on all exposed endpoints. When executing the above command the image automatically generates a username/password pair with the admin role, prints the values to stdout and then starts the Infinispan server with the authenticated endpoints exposed on port 11222. Therefore, it’s necessary to utilise the printed credentials when accessing the exposed endpoints via clients.

It is also possible to provide an administrator username/password combination via environment variables:

docker run -p 11222:11222 -e USER="admin" -e PASS="changeme" --name infinispan infinispan/server

podman run -p 11222:11222 -e USER="admin" -e PASS="changeme" --net=host --name infinispan infinispan/server

When connecting a Hot Rod client to the image, the following SASL properties must be configured on your client (with the username and password properties changed as required):

infinispan.client.hotrod.auth_username=admin
infinispan.client.hotrod.auth_password=changme
infinispan.client.hotrod.sasl_mechanism=DIGEST-MD5

User identities and roles can be defined by providing a cli batch file via the IDENTITIES_BATCH env variable. All the cli commands defined in this file are executed before the server is started, therefore it iss only possible to execute offline commands otherwise the container will fail. For example, including create cache …​ in the batch would fail as it requires a connection to an Infinispan server.

Data Grid provides implicit roles for some users.

Below is an example Identities batch CLI file identities.batch, that defines four users and their role:

user create "Alan Shearer" -p "striker9" -g admin
user create "observer" -p "secret1"
user create "deployer" -p "secret2"
user create "Rigoberta Baldini" -p "secret3" -g monitor

To run the image using a local identities.batch, execute:

docker run -v $(pwd):/user-config -e IDENTITIES_BATCH="/user-config/identities.batch" -p 11222:11222 --name infinispan infinispan/server

podman run -v $(pwd):/user-config -e IDENTITIES_BATCH="/user-config/identities.batch" -p 11222:11222 --net=host --name infinispan infinispan/server

The Infinispan image passes all container arguments to the created server, therefore it is possible to configure the server in the same manner as a non-containerised deployment.

Below shows how a docker volume can be created and mounted in order to run the Infinispan image with the local configuration file my-infinispan-config.xml located in the users current working directory.

docker run -v $(pwd):/user-config -e IDENTITIES_BATCH="/user-config/identities.batch" -p 11222:11222 --name infinispan infinispan/server -c /user-config/my-infinispan-config.xml

podman run -v $(pwd):/user-config -e IDENTITIES_BATCH="/user-config/identities.batch" -p 11222:11222 --net=host --name infinispan infinispan/server -c /user-config/my-infinispan-config.xml

docker run -v $(pwd):/user-config --name infinispan infinispan/server --bind-address=0.0.0.0  -Dinfinispan.cluster.stack=kubernetes -Djgroups.dns.query="infinispan-dns-ping.myproject.svc.cluster.local"

podman run -v $(pwd):/user-config --name infinispan infinispan/server --bind-address=0.0.0.0  -Dinfinispan.cluster.stack=kubernetes -Djgroups.dns.query="infinispan-dns-ping.myproject.svc.cluster.local"

docker run -e JAVA_OPTIONS="-Dinfinispan.cors.enableAll=https://host.domain:port" --name infinispan infinispan/server

podman run -e JAVA_OPTIONS="-Dinfinispan.cors.enableAll=https://host.domain:port" --net=host --name infinispan infinispan/server

docker run -e SERVER_LIBS="org.postgresql:postgresql:42.3.1" --name infinispan infinispan/server

podman run -e SERVER_LIBS="org.postgresql:postgresql:42.3.1" --name infinispan infinispan/server

Data Grid Server requires a Java Virtual Machine. See the Data Grid Supported Configurations for details on supported versions.

The Data Grid Server distribution is an archive of Java libraries (JAR files) and configuration files.

Install the Data Grid Server distribution on a host system.

unzip redhat-datagrid-8.6.0-server.zip

The resulting directory is your $RHDG_HOME.

Run Data Grid Server instances in a Java Virtual Machine (JVM) on any supported host.

Data Grid Server is running successfully when it logs the following messages:

ISPN080004: Protocol SINGLE_PORT listening on 127.0.0.1:11222
ISPN080034: Server '...' listening on http://127.0.0.1:11222
ISPN080001: Data Grid Server <version> started in <mm>ms

Specify custom configuration when you start Data Grid Server.

Data Grid Server can parse multiple configuration files that you overlay on startup with the --server-config argument. You can use as many configuration overlay files as required, in any order. Configuration overlay files:

Assign roles to users and grant them permissions to perform cache operations and interact with Data Grid resources.

user roles ls katie
["deployer"]

cat server/conf/groups.properties

Data Grid includes several roles that provide users with permissions to access caches and Data Grid resources.

Prevent data loss and ensure consistency of your cluster by properly shutting down and restarting nodes.

Cluster shutdown

Data Grid recommends using the shutdown cluster command to stop all nodes in a cluster while saving cluster state and persisting all data in the cache. You can use the shutdown cluster command also for clusters with a single node.

When you bring Data Grid clusters back online, all nodes and caches in the cluster will be unavailable until all nodes rejoin. To prevent inconsistencies or data loss, Data Grid restricts access to the data stored in the cluster and modifications of the cluster state until the cluster is fully operational again. Additionally, Data Grid disables cluster rebalancing and prevents local cache stores purging on startup.

During the cluster recovery process, the coordinator node logs messages for each new node joining, indicating which nodes are available and which are still missing. Other nodes in the Data Grid cluster have the view from the time they join. You can monitor availability of caches using the Data Grid Console or REST API.

However, in cases where waiting for all nodes is not necessary nor desired, it is possible to set a cache available with the current topology. This approach is possible through the CLI, see below, or the REST API.

Server shutdown

After using the shutdown server command to bring nodes down, the first node to come back online will be available immediately without waiting for other members. The remaining nodes join the cluster immediately, triggering state transfer but loading the local persistence first, which might lead to stale entries. Local cache stores configured to purge on startup will be emptied when the server starts. Local cache stores marked as purge=false will be available after a server restarts but might contain stale entries.

If you shutdown clustered nodes with the shutdown server command, you must restart each server in reverse order to avoid potential issues related to data loss and stale entries in the cache.
For example, if you shutdown server1 and then shutdown server2, you should first start server2 and then start server1. However, restarting clustered nodes in reverse order does not completely prevent data loss and stale entries.

Apart from resources in the bin and docs folders, the only folder under $RHDG_HOME that you should interact with is the server root directory, which is named server by default.

You can create multiple nodes under the same $RHDG_HOME directory or in different directories, but each Data Grid Server instance must have its own server root directory. For example, a cluster of 5 nodes could have the following server root directories on the filesystem:

├── server
├── server1
├── server2
├── server3
└── server4

Each server root directory should contain the following folders:

├── server
│   ├── conf
│   ├── data
│   ├── lib
│   └── log

server/conf

Holds infinispan.xml configuration files for a Data Grid Server instance.

Data Grid separates configuration into two layers:

server/data

Provides internal storage that Data Grid Server uses to maintain cluster state.

server/lib

Contains extension JAR files for custom filters, custom event listeners, JDBC drivers, custom ServerTask implementations, and so on.

server/log

Holds Data Grid Server log files.

Ansible collection

Automate installation of Data Grid clusters with our Ansible collection that optionally includes Keycloak caches and cross-site replication configuration. The Ansible collection also lets you inject Data Grid caches into the static configuration for each server instance during installation.

The Ansible collection for Data Grid is available from the Red Hat Automation Hub.