Upgrade migrations
editUpgrade migrations
editEvery time Kibana is upgraded it checks to see if all saved objects, such as dashboards, visualizations, and index patterns, are compatible with the new version. If any saved objects need to be updated, then the automatic saved object migration process is kicked off.
6.7 includes an Upgrade Assistant to help you prepare for your upgrade to 7.0. To access the assistant, go to Management > 7.0 Upgrade Assistant.
The following instructions assumes Kibana is using the default index names. If the kibana.index
or xpack.tasks.index
configuration settings were changed these instructions will have to be adapted accordingly.
Background
editSaved objects are stored in two indices:
-
.kibana_N
, or if set, thekibana.index
configuration setting -
.kibana_task_manager_N
, or if set, thexpack.tasks.index
configuration setting
For each of these indices, N
is a number that increments every time Kibana runs an upgrade migration on that index. The index aliases .kibana
and .kibana_task_manager
point to the most up-to-date index.
While Kibana is starting up and before serving any HTTP traffic, it checks to see if any internal mapping changes or data transformations for existing saved objects are required.
When changes are necessary, a new migration is started. To ensure that only one Kibana instance performs the migration, each instance will attempt to obtain a migration lock by creating a new .kibana_N+1
index. The instance that succeeds in creating the index will then read batches of documents from the existing index, migrate them, and write them to the new index. Once the objects are migrated, the lock is released by pointing the .kibana
index alias the new upgraded .kibana_N+1
index.
Instances that failed to acquire a lock will log Another Kibana instance appears to be migrating the index. Waiting for that migration to complete
. The instance will then wait until .kibana
points to an upgraded index before starting up and serving HTTP traffic.
Prior to 6.5.0, saved objects were stored directly in an index named .kibana
. After upgrading to version 6.5+, Kibana will migrate this index into .kibana_N
and set .kibana
up as an index alias.
Prior to 7.4.0, task manager tasks were stored directly in an index name .kibana_task_manager
. After upgrading to version 7.4+, Kibana will migrate this index into .kibana_task_manager_N
and set .kibana_task_manager
up as an index alias.
Preventing migration failures
editThis section highlights common causes of Kibana upgrade failures and how to prevent them.
Corrupt saved objects
editWe highly recommend testing your Kibana upgrade in a development cluster to discover and remedy problems caused by corrupt documents, especially when there are custom integrations creating saved objects in your environment. Saved objects that were corrupted through manual editing or integrations will cause migration failures with a log message like Failed to transform document. Transform: index-pattern:7.0.0\n Doc: {...}
or Unable to migrate the corrupt Saved Object document ...
. Corrupt documents will have to be fixed or deleted before an upgrade migration can succeed.
User defined index templates that causes new .kibana*
indices to have incompatible settings or mappings
editMatching index templates which specify settings.refresh_interval
or mappings
are known to interfere with Kibana upgrades.
Prevention: narrow down the index patterns of any user-defined index templates to ensure that these won’t apply to new .kibana*
indices.
Note: Kibana < 6.5 creates it’s own index template called kibana_index_template:.kibana
and index pattern .kibana
. This index template will not interfere and does not need to be changed or removed.
An unhealthy Elasticsearch cluster
editProblems with your Elasticsearch cluster can prevent Kibana upgrades from succeeding. Ensure that your cluster has:
-
enough free disk space, at least twice the amount of storage taken up by the
.kibana
and.kibana_task_manager
indices - sufficient heap size
- a "green" cluster status
Running different versions of Kibana connected to the same Elasticsearch index
editKibana does not support rolling upgrades. Stop all Kibana instances before starting a newer version to prevent upgrade failures and data loss.
Incompatible xpack.tasks.index
configuration setting
editFor Kibana < 7.5.1, if the task manager index is set to .tasks
with the configuration setting xpack.tasks.index: ".tasks"
, upgrade migrations will fail. Kibana 7.5.1 and later prevents this by refusing to start with an incompatible configuration setting.
Resolving migration failures
editIf Kibana terminates unexpectedly while migrating a saved object index, manual intervention is required before Kibana will attempt to perform the migration again. Follow the advice in (preventing migration failures)[preventing-migration-failures] before retrying a migration upgrade.
As mentioned above, Kibana will create a migration lock for each index that requires a migration by creating a new .kibana_N+1
index. For example: if the .kibana_task_manager
alias is pointing to .kibana_task_manager_5
then the first Kibana that succeeds in creating .kibana_task_manager_6
will obtain the lock to start migrations.
However, if the instance that obtained the lock fails to migrate the index, all other Kibana instances will be blocked from performing this migration. This includes the instance that originally obtained the lock, it will be blocked from retrying the migration even when restarted.
Retry a migration by restoring a backup snapshot:
edit-
Before proceeding ensure that you have a recent and successful backup snapshot of all
.kibana*
indices. - Shutdown all Kibana instances to be 100% sure that there are no instances currently performing a migration.
-
Delete all saved object indices with
DELETE /.kibana*
- Restore the `.kibana* indices and their aliases from the backup snapshot. See Elasticsearch snapshots
- Start up all Kibana instances to retry the upgrade migration.
(Not recommended) Retry a migration without a backup snapshot:
edit- Shutdown all Kibana instances to be 100% sure that there are no instances currently performing a migration.
-
Identify any migration locks by comparing the output of
GET /_cat/aliases
andGET /_cat/indices
. If e.g..kibana
is pointing to.kibana_4
and there is a.kibana_5
index, the.kibana_5
index will act like a migration lock blocking further attempts. Be sure to check both the.kibana
and.kibana_task_manager
aliases and their indices. -
Remove any migration locks e.g.
DELETE /.kibana_5
. - Start up all Kibana instances.
Rolling back to a previous version of Kibana
editIf you’ve followed the advice in (preventing migration failures)[preventing-migration-failures] and (resolving migration failures)[resolve-migrations-failures] and Kibana is still not able to upgrade successfully, you might choose to rollback Kibana until you’re able to identify the root cause.
Before rolling back Kibana, ensure that the version you wish to rollback to is compatible with your Elasticsearch cluster. If the version you’re rolling back to is not compatible, you will have to also rollback Elasticsearch.
Any changes made after an upgrade will be lost when rolling back to a previous version.
In order to rollback after a failed upgrade migration, the saved object indices might also have to be rolled back to be compatible with the previous {kibana} version.
Rollback by restoring a backup snapshot:
edit-
Before proceeding ensure that you have a recent and successful backup snapshot of all
.kibana*
indices. - Shutdown all Kibana instances to be 100% sure that there are no instances currently performing a migration.
-
Delete all saved object indices with
DELETE /.kibana*
- Restore the `.kibana* indices and their aliases from the backup snapshot. See Elasticsearch snapshots
- Start up all Kibana instances on the older version you wish to rollback to.
(Not recommended) Rollback without a backup snapshot:
editKibana does not run a migration for every saved object index on every upgrade. A Kibana version upgrade can cause no migrations, migrate only the .kibana
or the .kibana_task_manager
index or both. Carefully read the logs to ensure that you’re only deleting indices created by a later version of Kibana to avoid data loss.
- Shutdown all Kibana instances to be 100% sure that there are no Kibana instances currently performing a migration.
-
Create a backup snapshot of the
.kibana*
indices. -
Use the logs from the upgraded instances to identify which indices Kibana attempted to upgrade. The server logs will contain an entry like
[savedobjects-service] Creating index .kibana_4.
and/or[savedobjects-service] Creating index .kibana_task_manager_2.
If no indices were created after upgrading Kibana then no further action is required to perform a rollback, skip ahead to step (5). If you’re running multiple Kibana instances, be sure to inspect all instances' logs. -
Delete each of the indices identified in step (2). e.g.
DELETE /.kibana_task_manager_2
-
Inspect the output of
GET /_cat/aliases
. If either the.kibana
and/or.kibana_task_manager
alias is missing, these will have to be created manually. Find the latest index from the output ofGET /_cat/indices
and create the missing alias to point to the latest index. E.g. if the.kibana
alias was missing and the latest index is.kibana_3
create a new alias withPOST /.kibana_3/_aliases/.kibana
. - Start up Kibana on the older version you wish to rollback to.
Handling old .kibana_N
indices
editAfter migrations have completed, there will be multiple Kibana indices in Elasticsearch: (.kibana_1
, .kibana_2
, etc). Kibana only uses the index that the .kibana
alias points to. The other Kibana indices can be safely deleted, but are left around as a matter of historical record, and to facilitate rolling Kibana back to a previous version.