Learn how to upgrade and migrate your Infinispan deployments to the latest version or between later versions. Find out how to perform rolling upgrades of Infinispan Server deployments and how to migrate persistent data between cache stores.
1. Infinispan Version Details
Learn about changes in Infinispan versions before you upgrade.
include::../topics/upgrading.adoc
2. Performing rolling upgrades for Infinispan Server clusters
Perform rolling upgrades of your Infinispan clusters to change between versions without downtime or data loss and migrate data over the Hot Rod protocol.
2.1. Setting up target Infinispan clusters
Create a cluster that uses the Infinispan version to which you plan to upgrade and then connect the source cluster to the target cluster using a remote cache store.
-
Install Infinispan Server nodes with the desired version for your target cluster.
|
Ensure the network properties for the target cluster do not overlap with those for the source cluster. You should specify unique names for the target and source clusters in the JGroups transport configuration. Depending on your environment you can also use different network interfaces and port offsets to separate the target and source clusters. |
-
Create a remote cache store configuration, in JSON format, that allows the target cluster to connect to the source cluster.
Remote cache stores on the target cluster use the Hot Rod protocol to retrieve data from the source cluster.
{ "remote-store": { "cache": "myCache", "shared": true, "raw-values": true, "security": { "authentication": { "digest": { "username": "username", "password": "changeme", "realm": "default" } } }, "remote-server": [ { "host": "127.0.0.1", "port": 12222 } ] } } -
Use the Infinispan Command Line Interface (CLI) or REST API to add the remote cache store configuration to the target cluster so it can connect to the source cluster.
-
CLI: Use the
migrate cluster connectcommand on the target cluster.[//containers/default]> migrate cluster connect -c myCache --file=remote-store.json -
REST API: Invoke a POST request that includes the remote store configuration in the payload with the
rolling-upgrade/source-connectionmethod.POST /rest/v2/caches/myCache/rolling-upgrade/source-connection
-
-
Repeat the preceding step for each cache that you want to migrate.
-
Switch clients over to the target cluster, so it starts handling all requests.
-
Update client configuration with the location of the target cluster.
-
Restart clients.
-
|
If you need to migrate Indexed caches you must first migrate the internal |
2.2. Synchronizing data to target clusters
When you set up a target Infinispan cluster and connect it to a source cluster, the target cluster can handle client requests using a remote cache store and load data on demand. To completely migrate data to the target cluster, so you can decommission the source cluster, you can synchronize data. This operation reads data from the source cluster and writes it to the target cluster. Data migrates to all nodes in the target cluster in parallel, with each node receiving a subset of the data. You must perform the synchronization for each cache that you want to migrate to the target cluster.
-
Set up a target cluster with the appropriate Infinispan version.
-
Start synchronizing each cache that you want to migrate to the target cluster with the Infinispan Command Line Interface (CLI) or REST API.
-
CLI: Use the
migrate cluster synchronizecommand.migrate cluster synchronize -c myCache -
REST API: Use the
?action=sync-dataparameter with a POST request.POST /rest/v2/caches/myCache?action=sync-dataWhen the operation completes, Infinispan responds with the total number of entries copied to the target cluster.
-
-
Disconnect each node in the target cluster from the source cluster.
-
CLI: Use the
migrate cluster disconnectcommand.migrate cluster disconnect -c myCache -
REST API: Invoke a DELETE request.
DELETE /rest/v2/caches/myCache/rolling-upgrade/source-connection
-
After you synchronize all data from the source cluster, the rolling upgrade process is complete. You can now decommission the source cluster.
3. Patching Infinispan Server installations
Install and manage patches for Infinispan Server installations.
You can apply patches to multiple Infinispan Server installations with different versions to upgrade to a desired target version. However, patches do not take effect if Infinispan Server is running. If you want to upgrade Infinispan clusters without downtime, create a new cluster with the target version and perform a rolling upgrade to that version instead of patching.
3.1. Infinispan Server patches
Infinispan Server patches are .zip archives that contain artifacts that you can apply to your $ISPN_HOME directory to fix issues and add new features.
Patches also provide a set of rules for Infinispan Server to modify your installation. When you apply patches, Infinispan overwrites some files and removes others, depending on if they are required for the target version.
However, Infinispan does not make any changes to configuration files that you have created or modified when applying a patch. Server patches do not modify or replace any custom configuration or data.
3.2. Creating Infinispan Server patches
You can create patches for Infinispan Server from an existing installation.
You can create patches for Infinispan Server starting from version 10.1.7. You can patch any 10.1 or later server installation. However you cannot patch 9.4.x or earlier servers with 10.1.7 or later.
You can also create patches that either upgrade or downgrade the Infinispan Server version. For example, you can create a patch from version 10.1.7 and use it to upgrade version 10.1.5 or downgrade version 11.0.0.
-
Navigate to
$ISPN_HOMEfor a Infinispan Server installation that has the target version for the patch you want to create. -
Start the CLI.
bin/cli.sh -
Use the
patch createcommand to generate a patch archive and include the-qoption with a meaningful qualifier to describe the patch.patch create -q "this is my test patch" path/to/mypatch.zip \ path/to/target/server/home path/to/source/server/homeThe preceding command generates a
.ziparchive in the specified directory. Paths are relative to$ISPN_HOMEfor the target server.Create single patches for multiple different Infinispan versions, for example:
patch create -q "this is my test patch" path/to/mypatch.zip \ path/to/target/server/home \ path/to/source/server1/home path/to/source/server2/homeWhere
server1andserver2are different Infinispan versions where you can install "mypatch.zip". -
Describe the generated patch archive.
patch describe path/to/mypatch.zipInfinispan patch target=$target_version(my test patch) source=$source_version created=$timestamp-
$target_versionis the Infinispan version from which the patch was created. -
$source_versionis one or more Infinispan versions to which you can apply the patch.You can apply patches to Infinispan Server installations that match the
$source_versiononly.
-
3.3. Applying patches to Infinispan Server installations
Upgrade or downgrade Infinispan Server installation to a Infinispan version by installing patches.
-
Create a server patch for the target version.
-
Navigate to
$ISPN_HOMEfor the Infinispan Server installation you want to patch. -
Stop the Infinispan Server if it is running.
If you patch a server while it is running, the version changes take effect after restart. If you do not want to stop the server, create a new cluster with the target version and perform a rolling upgrade to that version instead of patching.
-
Start the CLI.
bin/cli.sh -
Install the patch.
[disconnected]> patch install path/to/patch.zip Infinispan patch target=$target_version source=$source_version \ created=$timestamp installed=$timestamp-
$target_versiondisplays the Infinispan version that the patch installed. -
$source_versiondisplays the Infinispan version before you installed the patch.
-
-
Start the server to verify the patch is installed.
bin/server.sh ... ISPN080001: Infinispan Server $versionIf the patch is installed successfully
$versionmatches$target_version.
|
Use the
|
3.4. Rolling back patches
Remove patches from Infinispan Server by rolling them back and restoring the previous Infinispan version.
|
If a server has multiple patches installed, you can roll back the last installed patch only. Rolling back patches does not revert configuration changes you make to Infinispan Server. Before you roll back patches, you should ensure that your configuration is compatible with the version to which you are rolling back. |
-
Navigate to
$ISPN_HOMEfor the Infinispan Server installation you want to roll back. -
Stop the server if it is running.
-
Start the CLI.
bin/cli.sh -
List the installed patches.
patch lsInfinispan patch target=$target_version source=$source_version created=$timestamp installed=$timestamp-
$target_versionis the Infinispan server version after the patch was applied. -
$source_versionis the version for Infinispan server before the patch was applied. Rolling back the patch restores the server to this version.
-
-
Roll back the last installed patch.
patch rollback -
Quit the CLI.
quit -
Start the server to verify the patch is rolled back to the previous version.
bin/server.shISPN080001: Infinispan Server $versionIf the patch is rolled back successfully
$versionmatches$source_version.
|
Use the
|
4. Migrating data between cache stores
Infinispan provides a Java utility for migrating persistent data between cache stores.
In the case of upgrading Infinispan, functional differences between major
versions do not allow backwards compatibility between cache stores. You can use
StoreMigrator to convert your data so that it is compatible with the target
version.
For example, upgrading to Infinispan 10.0 changes the default marshaller to Protostream. In previous Infinispan versions, cache stores use a binary format that is not compatible with the changes to marshalling. This means that Infinispan 10.1 cannot read from cache stores with previous Infinispan versions.
In other cases Infinispan versions deprecate or remove cache store
implementations, such as JDBC Mixed and Binary stores. You can use
StoreMigrator in these cases to convert to different cache store
implementations.
4.1. Cache store migrator
Infinispan provides the CLI migrate store command that recreates data for the latest Infinispan cache store implementations.
The store migrator takes a cache store from a previous version of Infinispan as source and uses a cache store implementation as target.
When you run the store migrator, it creates the target cache with the cache store type that you define using the EmbeddedCacheManager interface.
The store migrator then loads entries from the source store into memory and then puts them into the target cache.
The store migrator also lets you migrate data from one type of cache store to another. For example, you can migrate from a JDBC string-based cache store to a SIFS cache store.
|
The store migrator cannot migrate data from segmented cache stores to:
|
4.2. Configuring the cache store migrator
Use the migrator.properties file to configure properties for source and target cache stores.
-
Create a
migrator.propertiesfile. -
Configure properties for source and target cache store using the
migrator.propertiesfile.-
Add the
source.prefix to all configuration properties for the source cache store.Example source cache storesource.type=SOFT_INDEX_FILE_STORE source.cache_name=myCache source.location=/path/to/source/sifs source.version=<version>For migrating data from segmented cache stores, you must also configure the number of segments using the
source.segment_countproperty. The number of segments must matchclustering.hash.numSegmentsin your Infinispan configuration. If the number of segments for a cache store does not match the number of segments for the corresponding cache, Infinispan cannot read data from the cache store. -
Add the
target.prefix to all configuration properties for the target cache store.Example target cache storetarget.type=SINGLE_FILE_STORE target.cache_name=myCache target.location=/path/to/target/sfs.dat
-
4.2.1. Configuration properties for the cache store migrator
Configure source and target cache stores in a StoreMigrator properties.
| Property | Description | Required/Optional |
|---|---|---|
|
Specifies the type of cache store for a source or target cache store.
|
Required |
| Property | Description | Example Value | Required/Optional |
|---|---|---|---|
|
The name of the cache that you want to back up. |
|
Required |
|
The number of segments for target cache stores that can use segmentation. The number of segments must match |
|
Optional |
|
Specifies a custom marshaller class. |
Required if using custom marshallers. |
|
Specifies a comma-separated list of fully qualified class names that are allowed to be deserialized. |
Optional |
|
Specifies a comma-separated list of regular expressions that determine which classes are allowed be deserialized. |
Optional |
|
Specifies a comma-separated list of custom |
Optional |
| Property | Description | Required/Optional |
|---|---|---|
|
Specifies the dialect of the underlying database. |
Required |
|
Specifies the marshaller version for source cache stores. |
Required for source stores only. |
|
Specifies the JDBC connection URL. |
Required |
|
Specifies the class of the JDBC driver. |
Required |
|
Specifies a database username. |
Required |
|
Specifies a password for the database username. |
Required |
|
Disables database upsert. |
Optional |
|
Specifies if table indexes are created. |
Optional |
|
Specifies additional prefixes for the table name. |
Optional |
|
Specifies the column name. |
Required |
|
Specifies the column type. |
Required |
|
Specifies the |
Optional |
|
To migrate from Binary cache stores in older Infinispan versions, change
|
# Example configuration for migrating to a JDBC String-Based cache store target.type=STRING target.cache_name=myCache target.dialect=POSTGRES target.marshaller.class=org.infinispan.commons.marshall.JavaSerializationMarshaller target.marshaller.allow-list.classes=org.example.Person,org.example.Animal target.marshaller.allow-list.regexps="org.another.example.*" target.marshaller.externalizers=25:Externalizer1,org.example.Externalizer2 target.connection_pool.connection_url=jdbc:postgresql:postgres target.connection_pool.driver_class=org.postrgesql.Driver target.connection_pool.username=postgres target.connection_pool.password=redhat target.db.disable_upsert=false target.db.disable_indexing=false target.table.string.table_name_prefix=tablePrefix target.table.string.id.name=id_column target.table.string.data.name=datum_column target.table.string.timestamp.name=timestamp_column target.table.string.id.type=VARCHAR target.table.string.data.type=bytea target.table.string.timestamp.type=BIGINT target.key_to_string_mapper=org.infinispan.persistence.keymappers. DefaultTwoWayKey2StringMapper
| Property | Description | Required/Optional |
|---|---|---|
|
Sets the database directory. |
Required |
|
Specifies the compression type to use. |
Optional |
# Example configuration for migrating from a RocksDB cache store. source.type=ROCKSDB source.cache_name=myCache source.location=/path/to/rocksdb/database source.compression=SNAPPY
| Property | Description | Required/Optional |
|---|---|---|
|
Sets the directory that contains the cache store |
Required |
# Example configuration for migrating to a Single File cache store. target.type=SINGLE_FILE_STORE target.cache_name=myCache target.location=/path/to/sfs.dat
| Property | Description | Required/Optional |
|---|---|---|
|
Sets the database directory. |
Required |
|
Sets the database index directory. |
Required for target cache stores. |
# Example configuration for migrating to a Soft-Index File cache store. target.type=SOFT_INDEX_FILE_STORE target.cache_name=myCache target.location=path/to/sifs/database target.location=path/to/sifs/index
4.3. Migrating Infinispan cache stores
Run the store migrator to migrate data from one cache store to another.
-
Get the Infinispan CLI.
-
Create a
migrator.propertiesfile that configures the source and target cache stores.
-
Run the
migrate store -p /path/to/migrator.propertiesCLI command