---
type: api
title: Migrate to data tiers routing
description: Switch the indices, ILM policies, and legacy, composable, and component templates from using custom node attributes and attribute-based allocation filters to using data tiers.
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/operation/operation-ilm-migrate-to-data-tiers
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/operation/operation-ilm-migrate-to-data-tiers
products:
  - Elasticsearch
---

# Migrate to data tiers routing

Availability: 7.14+

## Paths

- `POST` `/_ilm/migrate_to_data_tiers`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#basicauth)
- [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#bearerauth)

## Description

Switch the indices, ILM policies, and legacy, composable, and component templates from using custom node attributes and attribute-based allocation filters to using data tiers.
Optionally, delete one legacy index template.
Using node roles enables ILM to automatically move the indices between data tiers.

Migrating away from custom node attributes routing can be manually performed.
This API provides an automated way of performing three out of the four manual steps listed in the migration guide:

1. Stop setting the custom hot attribute on new indices.
1. Remove custom allocation settings from existing ILM policies.
1. Replace custom allocation settings from existing indices with the corresponding tier preference.

ILM must be stopped before performing the migration.
Use the stop ILM and get ILM status APIs to wait until the reported operation mode is `STOPPED`.

[About migrating index allocation](https://www.elastic.co/docs/manage-data/lifecycle/index-lifecycle-management/migrate-index-allocation-filters-to-node-roles)

## Query String Parameters

- `dry_run` (boolean · default: false)
  If true, simulates the migration from node attributes based allocation filters to data tiers, but does not perform the migration.
This provides a way to retrieve the indices and ILM policies that need to be migrated.
- `master_timeout` (string Duration · default: 30s)
  The period to wait for a connection to the master node.
If no response is received before the timeout expires, the request fails and returns an error.
It can also be set to `-1` to indicate that the request should never timeout.

## Request Body

`application/json`

- `legacy_template_to_delete` (string) — optional
- `node_attribute` (string) — optional

## Response

`application/json`

- `dry_run` (boolean)
- `removed_legacy_template` (string)
  The name of the legacy index template that was deleted.
This information is missing if no legacy index templates were deleted.
- `migrated_ilm_policies` ([] string)
  The ILM policies that were updated.
- `migrated_indices` (string Indices)
  The indices that were migrated to tier preference routing.
- `migrated_legacy_templates` ([] string)
  The legacy index templates that were updated to not contain custom routing settings for the provided data attribute.
- `migrated_composable_templates` ([] string)
  The composable index templates that were updated to not contain custom routing settings for the provided data attribute.
- `migrated_component_templates` ([] string)
  The component templates that were updated to not contain custom routing settings for the provided data attribute.
## Code Examples

#### Console

```console
POST /_ilm/migrate_to_data_tiers
{
  "legacy_template_to_delete": "global-template",
  "node_attribute": "custom_attribute_name"
}
```

#### JavaScript

```javascript
const response = await client.ilm.migrateToDataTiers({
  legacy_template_to_delete: "global-template",
  node_attribute: "custom_attribute_name",
});
```

#### Python

```python
resp = client.ilm.migrate_to_data_tiers(
    legacy_template_to_delete="global-template",
    node_attribute="custom_attribute_name",
)
```

#### curl

```curl
curl -X POST "$ELASTICSEARCH_URL/_ilm/migrate_to_data_tiers" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "legacy_template_to_delete": "global-template",
    "node_attribute": "custom_attribute_name"
  }'
```

#### Java

```java
client.ilm().migrateToDataTiers(m -> m
    .legacyTemplateToDelete("global-template")
    .nodeAttribute("custom_attribute_name")
);
```

#### C#

```c#
var response = await client.IndexLifecycleManagement
    .MigrateToDataTiersAsync(d1 => d1
        .LegacyTemplateToDelete("global-template")
        .NodeAttribute("custom_attribute_name")
    );
```

#### PHP

```php
$resp = $client->ilm()->migrateToDataTiers([
    "body" => [
        "legacy_template_to_delete" => "global-template",
        "node_attribute" => "custom_attribute_name",
    ],
]);
```

#### Ruby

```ruby
response = client.ilm.migrate_to_data_tiers(
  body: {
    "legacy_template_to_delete": "global-template",
    "node_attribute": "custom_attribute_name"
  }
)
```

## Response Examples

#### Migrate to data tiers response example1

A successful response when migrating indices, ILMs, and templates from custom node attributes to data tiers.

```json
{
  "dry_run": false,
  "removed_legacy_template":"global-template",
  "migrated_ilm_policies":["policy_with_allocate_action"],
  "migrated_indices":["warm-index-to-migrate-000001"],
  "migrated_legacy_templates":["a-legacy-template"],
  "migrated_composable_templates":["a-composable-template"],
  "migrated_component_templates":["a-component-template"]
}
```