elasticsearch/docs/reference/migration/apis/feature-migration.asciidoc

[role="xpack"]
[[feature-migration-api]]
=== Feature migration APIs
++++
<titleabbrev>Feature migration</titleabbrev>
++++

include::{es-repo-dir}/migration/apis/shared-migration-apis-tip.asciidoc[]

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.

[[feature-migration-api-request]]
==== {api-request-title}

`GET /_migration/system_features`

`POST /_migration/system_features`

[[feature-migration-api-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the `manage`
<<privileges-list-cluster,cluster privilege>> to use this API.

[[feature-migration-api-desc]]
==== {api-description-title}

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.

[[feature-migration-api-example]]
==== {api-examples-title}

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.

[source,console]
--------------------------------------------------
GET /_migration/system_features
--------------------------------------------------

Example response:

[source,console-result]
--------------------------------------------------
{
  "features" : [
    {
      "feature_name" : "async_search",
      "minimum_index_version" : "8.0.0",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "enrich",
      "minimum_index_version" : "8.0.0",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "fleet",
      "minimum_index_version" : "8.0.0",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "geoip",
      "minimum_index_version" : "8.0.0",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "kibana",
      "minimum_index_version" : "8.0.0",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "logstash_management",
      "minimum_index_version" : "8.0.0",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "machine_learning",
      "minimum_index_version" : "8.0.0",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "searchable_snapshots",
      "minimum_index_version" : "8.0.0",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "security",
      "minimum_index_version" : "8.0.0",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "tasks",
      "minimum_index_version" : "8.0.0",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "transform",
      "minimum_index_version" : "8.0.0",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "watcher",
      "minimum_index_version" : "8.0.0",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    }
  ],
  "migration_status" : "NO_MIGRATION_NEEDED"
}
--------------------------------------------------
// TESTRESPONSE[s/"minimum_index_version" : "8.0.0"/"minimum_index_version" : $body.$_path/]


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.

[source,console]
--------------------------------------------------
POST /_migration/system_features
--------------------------------------------------

Example response:

[source,console-result]
--------------------------------------------------
{
  "accepted" : true,
  "features" : [
    {
      "feature_name" : "security" <1>
    }
  ]
}
--------------------------------------------------
// TESTRESPONSE[skip: can't actually upgrade system indices in these tests]

<1> {es} security will be migrated before the cluster is upgraded.

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