Migration of configuration files

Owned by Ivan Senic
May 05, 2017

We want to ensure as less as possible manual work when the CMR needs to be upgraded to new version. One part of update process it to migrate the configuration files from old version to the new one. inspectIT currently automatically migrates all the files related to the Configuration interface:

  • Environments
  • Profiles
  • Agent mappings
  • Business definition
  • Alerting definition

Process

Setup

The migration is done using the XLST files, which are used to transform existing XML files. These files are stored in the inspectit.sevrer/src/main/external-resources/ci/schema/migration folder. The files names are representing the order of the migration during time:

-rw-r--r-- 1 ise ise 1444 апр 28 15:03 0001-add-schema-version-attribute.xml
-rw-r--r-- 1 ise ise  735 апр 28 15:03 0002-new-properties-jmx-sensor.xml
-rw-r--r-- 1 ise ise  630 апр 28 15:03 0003-add-retransformation-strategy.xml
-rw-r--r-- 1 ise ise 1112 апр 28 15:03 0004-remote-sensors-types-environment.xml

The first four characters define the identification of the schema version that will be active the file has been migrated with the XLST file. Rest of the name is explaining what is migration about and developer can choose it freely.

The schema version information is also written to any configuration file that we create:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profile schemaVersion="4" id="ejb_v2" name="EJB v2" common="true" created-on="2015-02-24T12:00:00" description="Profile for the EJBs (versions 1.x and 2.x)."
....

Current schema version is also hard coded in the source code:

/**
 * Interface for XML types (POJOs) that are aware of their schema version.
 *
 * @author Ivan Senic
 *
 */
public interface ISchemaVersionAware {

	/**
	 * Sets the schema version. Usually called before marshaling.
	 *
	 * @param schemaVersion
	 *            version
	 */
	void setSchemaVersion(int schemaVersion);

	/**
	 * Information about schema version for the configuration interface.
	 *
	 * @author Ivan Senic
	 *
	 */
	interface ConfigurationInterface {

		/** Current version. */
		int SCHEMA_VERSION = 4;
	}
}

Migration

Once CMR starts it checked if there are any configuration files that are having smaller schema version then the one hard coded in the source code. If this is the case, it goes to the migration XSLT files and applies all of them in order.

For example if configuration file is in version 2 and active schema version is 4, then CMR will apply first 0003-add-retransformation-strategy.xml and then 0004-remote-sensors-types-environment.xml migrations. This way configuration file will be migrated to version 4 and can be loaded. In addition migrated file will be overwritten on the disk.

For Developers

If you need to add new migration as the code you are adding needs to modify old configuration file, please do following steps:

  • Increase schema version in the ISchemaVersionAware interface
  • Create migration file with updated schema version in the file name (look to existing files to understand how XLST works)
  • Update schema version to newer version in all Common profiles (as they are in the Git repo this must be done)