Index Lifecycle Management REST spec and documentation

[codebrain]

The following issues have been encountered when implementing the ILM Apis in version 6.7.0 of the .NET client - elastic/elasticsearch-net#3671

Specifications

• The id path parameters in the REST JSON specifications take the form <name>_id. Specifications use {policy} as the path parameter, should be renamed to {policy_id}.

  • ilm.delete_lifecycle.json
  • ilm.get_lifecycle.json
  • ilm.put_lifecycle.json

• Where a path parameter is required, the "required": true json property should be set.

  • ilm.delete_lifecycle.json ({policy_id} parameter)
  • ilm.explain_lifecycle ({index} parameter)
  • ilm.move_to_step ({index} parameter)
  • ilm.put_lifecycle ({policy_id} parameter)
  • ilm.remove_policy ({index} parameter)
  • ilm.retry ({index} parameter)

• The params master_timeout and timeout are common across all specifications, but no common file is provided. Therefore, please include these parameters in each specification file.

  • ilm.* (applies to all specifications)

• The specifications have dropped the xpack.* prefix in the filename and specification key name. Not an issue per se, but it is inconsistent with the other APIs in 6.7.0

Documentation

• Request documentation uses policy_id but Path Parameters documentation uses policy, use policy_id (as per specification change requested above)

  • https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-put-lifecycle.html
  • https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-get-lifecycle.html
  • https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-delete-lifecycle.html

• Phase new is used in the Examples documentation in the following places, but is not found in the list of valid lifecycles

  elasticsearch/x-pack/plugin/core/src/test/java/org/elasticsearch/xpack/core/indexlifecycle/LifecyclePolicyTests.java

  Line 91 in a3030c5

  public static LifecyclePolicy randomTimeseriesLifecyclePolicyWithAllPhases(@Nullable String lifecycleName) {

  or the documentation https://www.elastic.co/guide/en/elasticsearch/reference/current/index-lifecycle-management.html. The following documentation is affected.
  • https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-move-to-step.html
  • https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-explain-lifecycle.html

• Default values for boolean types should adhere to the JSON encoded specification.

  • ilm.explain_lifecycle.json - "default" : "false", should be "default" : false, - without the quotes.

.NET client workarounds

In order to workaround the issues with the specifications in the .NET client we have the ability to patch/replace the specifications as demonstrated here - https://github.com/elastic/elasticsearch-net/tree/6.x/src/CodeGeneration/ApiGenerator/RestSpecification/XPack/Ilm - provided here as a reference.

[elasticmachine]

Pinging @elastic/es-core-features

[dakrone]

This has been open for quite a while, and we haven't made much progress on this due to focus in other areas. For now I'm going to close this as something we aren't planning on implementing. We can re-open it later if needed.