Upgrading Infinispan deployments

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.

Prerequisites

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.

Procedure

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 connect command 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-connection method.
  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.
1. Update client configuration with the location of the target cluster.
2. Restart clients.

If you need to migrate Indexed caches you must first migrate the internal ___protobuf_metadata cache so that the .proto schemas defined on the source cluster will also be present on the target cluster.

Additional resources

Remote cache store configuration schema

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.

Prerequisites

Set up a target cluster with the appropriate Infinispan version.

Procedure

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 synchronize command.
  migrate cluster synchronize -c myCache
- REST API: Use the ?action=sync-data parameter with a POST request.
  POST /rest/v2/caches/myCache?action=sync-data
  When 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 disconnect command.
  migrate cluster disconnect -c myCache
- REST API: Invoke a DELETE request.
  DELETE /rest/v2/caches/myCache/rolling-upgrade/source-connection

Next steps

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.

Procedure

Navigate to $ISPN_HOME for 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 create command to generate a patch archive and include the -q option 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/home

The preceding command generates a .zip archive in the specified directory. Paths are relative to $ISPN_HOME for 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/home

Where server1 and server2 are different Infinispan versions where you can install "mypatch.zip".

Describe the generated patch archive.
```
patch describe path/to/mypatch.zip
```
```
Infinispan patch target=$target_version(my test patch)  source=$source_version created=$timestamp
```
- $target_version is the Infinispan version from which the patch was created.
- $source_version is one or more Infinispan versions to which you can apply the patch.
  
  You can apply patches to Infinispan Server installations that match the $source_version only.

3.3. Applying patches to Infinispan Server installations

Upgrade or downgrade Infinispan Server installation to a Infinispan version by installing patches.

Prerequisites

Create a server patch for the target version.

Procedure

Navigate to $ISPN_HOME for 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_version displays the Infinispan version that the patch installed.
- $source_version displays the Infinispan version before you installed the patch.
Start the server to verify the patch is installed.
```
bin/server.sh
...
ISPN080001: Infinispan Server $version
```
If the patch is installed successfully $version matches $target_version.

Use the --server option to install patches in a different $ISPN_HOME directory, for example:

patch install path/to/patch.zip --server=path/to/server/home

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.

Procedure

Navigate to $ISPN_HOME for 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 ls
```
```
Infinispan patch target=$target_version source=$source_version
created=$timestamp installed=$timestamp
```
- $target_version is the Infinispan server version after the patch was applied.
- $source_version is 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.sh
```
```
ISPN080001: Infinispan Server $version
```
If the patch is rolled back successfully $version matches $source_version.

Use the --server option to rollback patches in a different $ISPN_HOME directory, for example:

patch rollback --server=path/to/server/home

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:

Non-segmented cache store.
Segmented cache stores that have a different number of segments.

4.2. Configuring the cache store migrator

Use the migrator.properties file to configure properties for source and target cache stores.

Procedure

Create a migrator.properties file.

Configure properties for source and target cache store using the migrator.properties file.

Add the source. prefix to all configuration properties for the source cache store.

Example source cache store

source.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_count property. The number of segments must match clustering.hash.numSegments in 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 store
```
target.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.

Table 1. Cache Store Type Property
Property	Description	Required/Optional
`type`	Specifies the type of cache store for a source or target cache store. `.type=JDBC_STRING` `.type=JDBC_BINARY` `.type=JDBC_MIXED` `.type=LEVELDB` `.type=ROCKSDB` `.type=SINGLE_FILE_STORE` `.type=SOFT_INDEX_FILE_STORE` `.type=JDBC_MIXED`	Required

Table 2. Common Properties
Property	Description	Example Value	Required/Optional
`cache_name`	The name of the cache that you want to back up.	`.cache_name=myCache`	Required
`segment_count`	The number of segments for target cache stores that can use segmentation. The number of segments must match `clustering.hash.numSegments` in the 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.	`.segment_count=256`	Optional
`marshaller.class`	Specifies a custom marshaller class.	Required if using custom marshallers.	`marshaller.allow-list.classes`
Specifies a comma-separated list of fully qualified class names that are allowed to be deserialized.	Optional	`marshaller.allow-list.regexps`	Specifies a comma-separated list of regular expressions that determine which classes are allowed be deserialized.
Optional	`marshaller.externalizers`	Specifies a comma-separated list of custom `AdvancedExternalizer` implementations to load in this format: `[id]:<Externalizer class>`	Optional

Table 3. JDBC Properties
Property	Description	Required/Optional
`dialect`	Specifies the dialect of the underlying database.	Required
`version`	Specifies the marshaller version for source cache stores. Set the value that matches the Infinispan major version of the source cluster. For example; set a value of `14` for Infinispan 14.x.	Required for source stores only.
`connection_pool.connection_url`	Specifies the JDBC connection URL.	Required
`connection_pool.driver_class`	Specifies the class of the JDBC driver.	Required
`connection_pool.username`	Specifies a database username.	Required
`connection_pool.password`	Specifies a password for the database username.	Required
`db.disable_upsert`	Disables database upsert.	Optional
`db.disable_indexing`	Specifies if table indexes are created.	Optional
`table.string.table_name_prefix`	Specifies additional prefixes for the table name.	Optional
`table.string.<id\|data\|timestamp>.name`	Specifies the column name.	Required
`table.string.<id\|data\|timestamp>.type`	Specifies the column type.	Required
`key_to_string_mapper`	Specifies the `TwoWayKey2StringMapper` class.	Optional

To migrate from Binary cache stores in older Infinispan versions, change table.string.* to table.binary.\* in the following properties:

source.table.binary.table_name_prefix
source.table.binary.<id\|data\|timestamp>.name
source.table.binary.<id\|data\|timestamp>.type

# 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

Table 4. RocksDB Properties
Property	Description	Required/Optional
`location`	Sets the database directory.	Required
`compression`	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

Table 5. SingleFileStore Properties
Property	Description	Required/Optional
`location`	Sets the directory that contains the cache store `.dat` file.	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

Table 6. SoftIndexFileStore Properties
Property	Description	Required/Optional
`location`	Sets the database directory.	Required
`index_location`	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.

Prerequisites

Get the Infinispan CLI.
Create a migrator.properties file that configures the source and target cache stores.

Procedure

Run the migrate store -p /path/to/migrator.properties CLI command