Upgrade Your Cluster to 0.55.x

Claus Matzinger, Chris Ward
Filed under
July 25, 2016

Version 0.55 of Crate introduces a lot of great features, fixes and changes. Some of these required making changes to our code base that require extra steps to upgrade your clusters than with previous Crate versions.

Note: Upgrading to 0.55 is only supported from Crate 0.52 and upwards.


Before upgrading a cluster it's strongly advised to create a backup of your current tables so you can always return to what you had before. Furthermore be prepared to restart your entire cluster.

Index Changes

Because of the Elasticsearch version upgrade, indices are not backwards compatible to 0.54. Be aware that once upgraded to 0.55, using the same index files in a 0.54 cluster will yield an error:

[2016-07-22 11:58:12,931][ERROR][gateway.local.state.shards] [Brian Braddock]
failed to read local state (started shards), exiting...
org.elasticsearch.ElasticsearchException: unexpected field in shard state

After upgrading your Crate version, indices will be rebuilt, and this process may take some time.

Settings Changes

There have been several changes and deprecations to the following settings in 0.55, some due to the underlying upgrade to Elasticsearch, and others made for reliability.

Configuration File and Location

You can no longer specify the name or location of the Crate configuration file with the CONF_FILE environment variable, -Des.config, -Des.default.config, or -Delasticsearch.config parameters. You must call it crate.yml and locate it in the config directory, or another directory specified by the CONF_DIR environmental variable, or by the -Des.path.home parameter. The file must be a yaml file that ends in the .yml extension.

Units Required

You must now define units for time or byte based settings. This affects Settings such as cluster.routing.allocation.disk.watermark.low for defining the lower disk threshold limit for shard allocations, or cluster.graceful*stop.timeout for defining the maximum wait in milliseconds for reallocation processes to finish. Please update your configuration accordingly.

For example:

cluster.graceful_stop.timeout: 1h
# Not…
cluster.graceful_stop.timeout: 1
cluster.routing.allocation.disk.watermark.low: 250mb
# Not…
cluster.routing.allocation.disk.watermark.low: 250

Translog Syncing

The gateway.local.sync setting for controlling the period after which the translog is synced to disk has been renamed to translog.sync_interval.

Bulk Operations

The bulk.partition_creation_timeout setting has been removed.

Automatic Job Termination

The jobs.keep_alive_timeout setting has been removed, meaning that you are no longer able to enable automatic job termination based on defined rules.

Other Changes

Crate Does Not Start on Plugin Errors

If one of your plugins does not load properly, Crate will now refuse to start. To remedy this, please remove any broken plugins from the plugins folder.

Disallowing "." Character in Field Names

Tables with column names that contain a dot are now disallowed. Consider re-creating the table and migrating the data via insert by query.

2016-07-22 11:25:15,651][ERROR][gateway] [Solo] failed to read local state,
java.lang.IllegalStateException: unable to upgrade the mappings for the index
[stocks], reason: [Field name [adj. close] cannot contain '.']

Get Help

For any questions you have on upgrading your (production) cluster, join our Slack channel, ask on Stackoverflow, or on Github.

Back to topAll posts