Skip to content

05 ‐ Procedimentos ILM

Jump to bottom
inhogoes edited this page May 8, 2026 · 3 revisions

5.1 - O que é o ILM

O ILM (Index Lifecycle Management) é o mecanismo nativo do Elasticsearch para automatizar o gerenciamento do ciclo de vida dos índices. Em vez de gerenciar manualmente quando um índice deve ser movido para um hardware mais barato ou quando deve ser deletado, o ILM faz isso de forma automática com base em regras chamadas policies.

O ILM é especialmente útil em cenários de dados temporais — logs, métricas, eventos de segurança — onde os dados perdem valor com o tempo e precisam ser retidos por um período determinado antes de serem descartados.

Por que usar ILM?

Sem o ILM, é comum que clusters acumulem índices antigos indefinidamente, consumindo disco e degradando o desempenho. Gerenciar isso manualmente é trabalhoso e propenso a erros. O ILM resolve isso com automação baseada em políticas declarativas.

Fases do ciclo de vida

Uma ILM policy é composta por fases, cada uma com suas próprias condições de entrada e ações a executar. As fases disponíveis são:

Fase Quando ocorre Ações típicas
Hot Fase inicial — o índice está sendo ativamente escrito e lido Rollover por tamanho, idade ou número de documentos
Warm O índice não recebe mais escritas, mas ainda é consultado com frequência Force merge, shrink, readonly, realocação para nodes warm
Cold Dados raramente consultados Realocação para nodes cold, searchable snapshots
Frozen Dados muito raramente acessados Searchable snapshots em object storage (S3, GCS)
Delete Dados que não precisam mais ser retidos Deleção do índice

Não é obrigatório usar todas as fases — uma policy pode ter apenas hot e delete, por exemplo.

Rollover

O rollover é a ação mais importante da fase hot. Ele cria um novo índice quando o índice atual atinge uma condição configurada:

  • max_size: tamanho total dos shards primários
  • max_age: tempo desde a criação do índice
  • max_docs: número de documentos

Quando o rollover acontece, o alias de escrita é movido automaticamente para o novo índice, sem nenhuma interrupção para quem está indexando.

Como o ILM se encaixa na arquitetura

O fluxo completo de uma implementação com ILM tem três peças:

ILM Policy → Index Template → Índice (gerenciado automaticamente)
  1. ILM Policy: define as regras de ciclo de vida
  2. Index Template: associa a policy a todos os índices que correspondem a um padrão de nome
  3. Índice inicial: criado com um alias de escrita — a partir daí, o ILM cuida do resto

5.2 - Laboratório: ILM com dados de vendas

Neste laboratório vamos configurar um ciclo de vida completo para um conjunto de dados de vendas. O índice será gerenciado automaticamente pelo ILM, com rollover na fase hot e deleção após um período configurado.

Todos os comandos devem ser executados no Kibana Dev Tools.

Nota sobre os timers do lab: os tempos configurados neste lab (segundos e minutos) são propositalmente curtos para que as transições entre fases sejam observáveis durante a aula. Em produção, os valores típicos são dias ou semanas.

Passo 1 — Ajustar o intervalo de verificação do ILM

Por padrão, o ILM verifica as condições das policies a cada 10 minutos. Para o lab, vamos reduzir para 10 segundos:

PUT /_cluster/settings
{
  "persistent": {
    "indices.lifecycle.poll_interval": "10s"
  }
}

Lembre-se de restaurar o valor padrão ao final do lab: defina indices.lifecycle.poll_interval como null.

Passo 2 — Criar a ILM Policy

PUT /_ilm/policy/policy-vendas
{
  "policy": {
    "phases": {
      "hot": {
        "min_age": "0ms",
        "actions": {
          "rollover": {
            "max_age": "1m",
            "max_docs": 5
          },
          "set_priority": {
            "priority": 100
          }
        }
      },
      "warm": {
        "min_age": "2m",
        "actions": {
          "forcemerge": {
            "max_num_segments": 1
          },
          "set_priority": {
            "priority": 50
          }
        }
      },
      "delete": {
        "min_age": "5m",
        "actions": {
          "delete": {}
        }
      }
    }
  }
}

Explicação das condições:

  • Hot → Rollover: acontece quando o índice tiver mais de 1 minuto ou mais de 5 documentos — o que ocorrer primeiro
  • Warm: o índice entra nessa fase 2 minutos após o rollover. O forcemerge compacta todos os segments em um único, otimizando leitura
  • Delete: o índice é deletado 5 minutos após entrar na fase de deleção

Passo 3 — Criar o Index Template

O template associa a ILM policy e o alias de rollover a todos os índices com o padrão vendas-*:

PUT /_index_template/sales
{
  "index_patterns": ["vendas-*"],
  "template": {
    "settings": {
      "number_of_shards": 1,
      "number_of_replicas": 1,
      "index.lifecycle.name": "policy-vendas",
      "index.lifecycle.rollover_alias": "vendas"
    },
    "mappings": {
      "properties": {
        "@timestamp":          { "type": "date" },
        "Category":            { "type": "keyword" },
        "City":                { "type": "keyword" },
        "Country":             { "type": "keyword" },
        "CustomerName":        { "type": "keyword" },
        "DaystoShipActual":    { "type": "long" },
        "DaystoShipScheduled": { "type": "long" },
        "Discount":            { "type": "double" },
        "OrderDate":           { "type": "date", "format": "iso8601" },
        "OrderID":             { "type": "keyword" },
        "OrderProfitable":     { "type": "keyword" },
        "PostalCode":          { "type": "long" },
        "ProductName":         { "type": "text" },
        "Profit":              { "type": "long" },
        "ProfitRatio":         { "type": "double" },
        "Quantity":            { "type": "long" },
        "Region":              { "type": "keyword" },
        "Sales":               { "type": "long" },
        "SalesForecast":       { "type": "long" },
        "SalesaboveTarget":    { "type": "keyword" },
        "SalesperCustomer":    { "type": "double" },
        "Segment":             { "type": "keyword" },
        "ShipDate":            { "type": "date", "format": "iso8601" },
        "ShipMode":            { "type": "keyword" },
        "ShipStatus":          { "type": "keyword" },
        "State":               { "type": "keyword" },
        "Sub_Category":        { "type": "keyword" },
        "latitude":            { "type": "double" },
        "location":            { "type": "geo_point" },
        "longitude":           { "type": "double" }
      }
    }
  }
}

Passo 4 — Criar o índice inicial com o alias de escrita

O primeiro índice precisa ser criado manualmente com o alias configurado como is_write_index: true. Esse alias é o que o ILM usa para saber para onde direcionar as novas escritas após cada rollover.

PUT /vendas-000001
{
  "aliases": {
    "vendas": {
      "is_write_index": true
    }
  }
}

A convenção de nomear o índice inicial com sufixo numérico (-000001) é exigida pelo mecanismo de rollover — o Elasticsearch incrementa esse número a cada rollover (-000002, -000003, etc.).

Passo 5 — Verificar que o ILM foi aplicado ao índice

GET /vendas-000001/_ilm/explain

O campo phase deve indicar hot e o campo action deve mostrar rollover. O campo age mostra quanto tempo o índice tem desde sua criação.

Passo 6 — Inserir documentos

Insira alguns documentos via alias. Note que usamos o alias vendas como destino — não o nome do índice diretamente. Isso garante que as escritas sempre vão para o índice ativo de escrita, independentemente de quantos rollovers já aconteceram.

POST /vendas/_doc
{
  "Category": "Office Supplies",
  "Discount": 0,
  "ProductName": "Xerox 214",
  "latitude": 41.6347,
  "PostalCode": 2740,
  "ShipStatus": "Shipped Early",
  "OrderID": "CA-2014-148355",
  "Segment": "Corporate",
  "SalesaboveTarget": "No",
  "Sales": 19,
  "SalesperCustomer": 19.44,
  "Profit": 9,
  "ShipMode": "Standard Class",
  "CustomerName": "Nick Crebassa",
  "DaystoShipScheduled": 6,
  "longitude": -70.9372,
  "Sub_Category": "Paper",
  "ProfitRatio": 48,
  "Quantity": 3,
  "City": "New Bedford",
  "ShipDate": "2014-12-29T00:00:00.000Z",
  "SalesForecast": 25,
  "OrderDate": "2014-12-25T00:00:00.000Z",
  "OrderProfitable": "No",
  "@timestamp": "2014-12-25T00:00:00.000Z",
  "State": "Massachusetts",
  "Country": "United States",
  "Region": "East",
  "location": "41.6347,-70.9372",
  "DaystoShipActual": 4
}

Insira mais 4 documentos para atingir a condição de rollover por max_docs: 5. Pode repetir o mesmo documento alterando o OrderID para simular registros diferentes.

Passo 7 — Acompanhar o rollover

Após inserir 5 documentos ou aguardar 1 minuto (o que ocorrer primeiro), o ILM deve executar o rollover automaticamente. Verifique:

GET /_cat/indices/vendas-*?v&s=index

Após o rollover, você verá dois índices: vendas-000001 (que saiu da fase hot) e vendas-000002 (novo índice ativo de escrita).

Verifique o alias:

GET /_cat/aliases/vendas?v

O is_write_index deve ter migrado para vendas-000002.

Acompanhe o estado do ILM em cada índice:

GET /vendas-*/_ilm/explain

Passo 8 — Acompanhar as transições de fase

Aguarde os tempos configurados e execute o comando abaixo repetidamente para observar as transições:

GET /vendas-000001/_ilm/explain

Os campos a observar:

Campo O que indica
phase Fase atual do índice (hot, warm, delete)
action Ação sendo executada na fase atual
step Etapa dentro da ação
age Tempo de vida do índice
phase_time Quando o índice entrou na fase atual

Passo 9 — Forçar uma transição manualmente (opcional)

Se quiser acelerar a transição para testes sem esperar o timer, use:

POST /_ilm/move/vendas-000001
{
  "current_step": {
    "phase": "hot",
    "action": "complete",
    "name": "complete"
  },
  "next_step": {
    "phase": "warm",
    "action": "forcemerge",
    "name": "forcemerge"
  }
}

Use com cautela — forçar transições em produção pode ter efeitos colaterais dependendo das ações configuradas na policy.

Passo 10 — Limpeza ao final do lab

Restaurar o intervalo de verificação do ILM para o valor padrão:

PUT /_cluster/settings
{
  "persistent": {
    "indices.lifecycle.poll_interval": null
  }
}

Por padrão, o Elasticsearch bloqueia deleções usando wildcard (*) para evitar remoção acidental de dados. Antes de deletar os índices do lab, é necessário desabilitar essa proteção temporariamente:

PUT /_cluster/settings
{
  "persistent": {
    "action.destructive_requires_name": false
  }
}

Remover os índices do lab:

DELETE /vendas-*

Após a limpeza, restaure a proteção:

PUT /_cluster/settings
{
  "persistent": {
    "action.destructive_requires_name": null
  }
}

Remover o template:

DELETE /_index_template/sales

Remover a policy:

DELETE /_ilm/policy/policy-vendas

5.3 - Gerenciando policies via Kibana

Além da API, é possível criar e gerenciar ILM policies diretamente pelo Kibana, sem escrever JSON. O caminho é:

Menu → Stack Management → Index Lifecycle Policies

A interface permite:

  • Criar e editar policies com um formulário visual
  • Visualizar todos os índices gerenciados por cada policy
  • Ver o estado atual de cada índice (fase, ação, possíveis erros)
  • Retentar steps com erro sem precisar usar a API

Para associar uma policy a um index template existente, vá em:

Menu → Stack Management → Index Management → Index Templates

Selecione o template desejado e edite a seção Index settings adicionando:

{
  "index.lifecycle.name": "nome-da-policy",
  "index.lifecycle.rollover_alias": "nome-do-alias"
}

5.4 - Operações úteis de ILM no dia a dia

Listar todas as policies:

GET /_ilm/policy

Ver o estado do ILM em todos os índices de um padrão:

GET /vendas-*/_ilm/explain

Ver apenas índices com erro no ILM:

GET /vendas-*/_ilm/explain?only_errors=true

Retentar um step com erro:

POST /vendas-000001/_ilm/retry

Ver o status geral do ILM no cluster:

GET /_ilm/status

Pausar o ILM globalmente (útil durante manutenções):

POST /_ilm/stop

Retomar o ILM:

POST /_ilm/start

5.5 - Curator: alternativa open source ao ILM

O Curator é uma ferramenta open source mantida pela Elastic para gerenciar o ciclo de vida de índices via linha de comando. Antes do ILM existir (versão 6.6), o Curator era a principal forma de automatizar tarefas como deleção de índices antigos, force merge e snapshot.

Hoje, com o ILM disponível nativamente e gratuito desde a versão 7.x, o Curator perdeu relevância em novas implementações. No entanto, ainda aparece em ambientes legados que migraram de versões antigas do Elasticsearch sem rever a gestão de índices.

Quando você ainda pode encontrar o Curator:

  • Clusters que foram instalados antes do ILM existir e nunca foram migrados
  • Ambientes com restrições que impedem o uso de features X-Pack (muito raros hoje)
  • Scripts de automação externos que gerenciam índices de forma imperativa

Para novas implementações, use o ILM. Ele é mais integrado, mais simples de configurar e não requer ferramentas externas.

Referência: github.com/elastic/curator

Clone this wiki locally