IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Stop index lifecycle management API Inference APIs »
Elastic Docs ›Elasticsearch Guide [8.11] ›REST APIs ›Index lifecycle management APIs

Migrate to data tiers routing API

edit

Migrate to data tiers routing API

edit

Switches the indices, ILM policies, and legacy, composable and component templates from using custom node attributes and attribute-based allocation filters to using data tiers, and optionally deletes 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 as indicated in the Migrate index allocation filters to node roles page.

This API provides an automated way of executing three out of the four manual steps listed in the migration guide:

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

Request

edit

POST /_ilm/migrate_to_data_tiers

The API accepts an optional body that allows you to specify:

  • The legacy index template name to delete. Defaults to none.
  • The name of the custom node attribute used for the indices and ILM policies allocation filtering. Defaults to data.

Prerequisites

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

Query parameters

edit
dry_run
(Optional, Boolean) 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. Defaults to false.

When simulating a migration (ie. dry_run is true) ILM doesn’t need to be stopped.

Examples

edit

The following example migrates the indices, ILM policies, legacy templates, composable, and component templates away from defining custom allocation filtering using the custom_attribute_name node attribute, and deletes the legacy template with name global-template if it exists in the system.

response = client.ilm.migrate_to_data_tiers(
  body: {
    legacy_template_to_delete: 'global-template',
    node_attribute: 'custom_attribute_name'
  }
)
puts response
POST /_ilm/migrate_to_data_tiers
{
  "legacy_template_to_delete": "global-template",
  "node_attribute": "custom_attribute_name"
}

If the request succeeds, a response like the following will be received:

{
  "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"] 
}

Shows the name of the legacy index template that was deleted. This will be missing if no legacy index template was deleted.

The ILM policies that were updated.

The indices that were migrated to tier preference routing.

The legacy index templates that were updated to not contain custom routing settings for the provided data attribute.

The composable index templates that were updated to not contain custom routing settings for the provided data attribute.

The component templates that were updated to not contain custom routing settings for the provided data attribute.
« Stop index lifecycle management API Inference APIs »