[role="xpack"]
[[ilm-migrate]]
=== Migrate

Phases allowed: warm, cold.

Moves the index to the <<data-tiers, data tier>> that corresponds
to the current phase by updating the <<tier-preference-allocation-filter, `index.routing.allocation.include._tier_preference`>>
index setting.
{ilm-init} automatically injects the migrate action in the warm and cold
phases if no allocation options are specified with the <<ilm-allocate, allocate>> action.
If you specify an allocate action that only modifies the number of index
replicas, {ilm-init} reduces the number of replicas before migrating the index.
To prevent automatic migration without specifying allocation options,
you can explicitly include the migrate action and set the enabled option to `false`.

In the warm phase, the `migrate` action sets <<tier-preference-allocation-filter, `index.routing.allocation.include._tier_preference`>>
to `data_warm,data_hot`. This moves the index to nodes in the
<<warm-tier, warm tier>>. If there are no nodes in the warm tier,  it falls back to the
<<hot-tier, hot tier>>.

In the cold phase, the `migrate` action sets
<<tier-preference-allocation-filter, `index.routing.allocation.include._tier_preference`>>
to `data_cold,data_warm,data_hot`. This moves the index to nodes in the
<<cold-tier, cold tier>>. If there are no nodes in the cold tier, it falls back to the
<<warm-tier, warm>> tier, or the <<hot-tier, hot>> tier if there are no warm nodes available.

The migrate action is not allowed in the hot phase.
The initial index allocation is performed <<data-tier-allocation, automatically>>,
and can be configured manually or via <<indices-templates, index templates>>.

[[ilm-migrate-options]]
==== Options

`enabled`::
(Optional, Boolean)
Controls whether {ilm-init} automatically migrates the index during this phase.
Defaults to `true`.

[[ilm-enabled-migrate-ex]]
==== Example

In the following policy, the allocate action is specified to reduce the number of replicas before {ilm-init} migrates the index to warm nodes.

NOTE: Explicitly specifying the migrate action is not required--{ilm-init} automatically performs the migrate action unless you specify allocation options or disable migration.

[source,console]
--------------------------------------------------
PUT _ilm/policy/my_policy
{
  "policy": {
    "phases": {
      "warm": {
        "actions": {
          "migrate" : {
          },
          "allocate": {
            "number_of_replicas": 1
          }
        }
      }
    }
  }
}
--------------------------------------------------

[[ilm-disable-migrate-ex]]
==== Disable automatic migration

The migrate action in the following policy is disabled and
the allocate action assigns the index to nodes that have a
`rack_id` of _one_ or _two_.
NOTE: Explicitly disabling the migrate action is not required--{ilm-init} does not inject the migrate action if you specify allocation options.
[source,console]
--------------------------------------------------
PUT _ilm/policy/my_policy
{
  "policy": {
    "phases": {
      "warm": {
        "actions": {
          "migrate" : {
           "enabled": false
          },
          "allocate": {
            "include" : {
              "rack_id": "one,two"
            }
          }
        }
      }
    }
  }
}
--------------------------------------------------