› › ›

Feature migration APIs

These APIs are designed for indirect use by Kibana’s Upgrade Assistant. We strongly recommend you use the Upgrade Assistant to upgrade from 7.17 to 8.17.3. For upgrade instructions, refer to Upgrading to Elastic 8.17.3.

Version upgrades sometimes require changes to how features store configuration information and data in system indices. The feature migration APIs enable you to see what features require changes, initiate the automatic migration process, and check migration status.

Some functionality might be temporarily unavailable during the migration process.

Request

GET /_migration/system_features

POST /_migration/system_features

Prerequisites

If the Elasticsearch security features are enabled, you must have the manage cluster privilege to use this API.

Description

Submit a GET request to the _migration/system_features endpoint to see what features need to be migrated and the status of any migrations that are in progress.

Submit a POST request to the endpoint to start the migration process.

Examples

When you submit a GET request to the _migration/system_features endpoint, the response indicates the status of any features that need to be migrated.

resp = client.migration.get_feature_upgrade_status()
print(resp)

response = client.migration.get_feature_upgrade_status
puts response

const response = await client.migration.getFeatureUpgradeStatus();
console.log(response);

GET /_migration/system_features

Example response:

{
  "features" : [
    {
      "feature_name" : "async_search",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "enrich",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "ent_search",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "fleet",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "geoip",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "kibana",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "logstash_management",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "machine_learning",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "searchable_snapshots",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "security",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "synonyms",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "tasks",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "transform",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "watcher",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    }
  ],
  "migration_status" : "NO_MIGRATION_NEEDED"
}

When you submit a POST request to the _migration/system_features endpoint to start the migration process, the response indicates what features will be migrated.

resp = client.migration.post_feature_upgrade()
print(resp)

response = client.migration.post_feature_upgrade
puts response

const response = await client.migration.postFeatureUpgrade();
console.log(response);

POST /_migration/system_features

Example response:

{
  "accepted" : true,
  "features" : [
    {
      "feature_name" : "security" 
    }
  ]
}

Elasticsearch security will be migrated before the cluster is upgraded.

Subsequent GET requests will return the status of the migration process.

© 2023-2025 Elasticsearch
As of September 2024, Elasticsearch is available under a choice of three licenses: the Server Side Public License (SSPL), the Elastic License, or the AGPLv3 (OSI approved).
Elasticsearch and the Elasticsearch logo are trademarks of Elasticsearch B.V., registered in the U.S. and in other countries.
https://www.elastic.co/guide/en/elasticsearch/reference/8.17/feature-migration-api.html