Create or update desired nodes API

Create or update desired nodes API

This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.

New API reference

For the most up-to-date API details, refer to Cluster APIs.

Creates or updates the desired nodes.

Request

  1. resp = client.perform_request(
  2.     "PUT",
  3.     "/_internal/desired_nodes/<history_id>/<version>",
  4.     headers={"Content-Type": "application/json"},
  5.     body={
  6.         "nodes": [
  7.             {
  8.                 "settings": {
  9.                     "node.name": "instance-000187",
  10.                     "node.external_id": "instance-000187",
  11.                     "node.roles": [
  12.                         "data_hot",
  13.                         "master"
  14.                     ],
  15.                     "node.attr.data": "hot",
  16.                     "node.attr.logical_availability_zone": "zone-0"
  17.                 },
  18.                 "processors": 8,
  19.                 "memory": "58gb",
  20.                 "storage": "2tb"
  21.             }
  22.         ]
  23.     },
  24. )
  25. print(resp)
  1. const response = await client.transport.request({
  2.   method: "PUT",
  3.   path: "/_internal/desired_nodes/<history_id>/<version>",
  4.   body: {
  5.     nodes: [
  6.       {
  7.         settings: {
  8.           "node.name": "instance-000187",
  9.           "node.external_id": "instance-000187",
  10.           "node.roles": ["data_hot", "master"],
  11.           "node.attr.data": "hot",
  12.           "node.attr.logical_availability_zone": "zone-0",
  13.         },
  14.         processors: 8,
  15.         memory: "58gb",
  16.         storage: "2tb",
  17.       },
  18.     ],
  19.   },
  20. });
  21. console.log(response);
  1. PUT /_internal/desired_nodes/<history_id>/<version>
  2. {
  3.     "nodes" : [
  4.         {
  5.             "settings" : {
  6.                  "node.name" : "instance-000187",
  7.                  "node.external_id": "instance-000187",
  8.                  "node.roles" : ["data_hot", "master"],
  9.                  "node.attr.data" : "hot",
  10.                  "node.attr.logical_availability_zone" : "zone-0"
  11.             },
  12.             "processors" : 8.0,
  13.             "memory" : "58gb",
  14.             "storage" : "2tb"
  15.         }
  16.     ]
  17. }

Query parameters

master_timeout

(Optional, time units) Period to wait for the master node. If the master node is not available before the timeout expires, the request fails and returns an error. Defaults to 30s. Can also be set to -1 to indicate that the request should never timeout.

dry_run

(Optional, Boolean) If true, then the request simulates the update and returns a response with dry_run field set to true.

Description

This API creates or update the desired nodes. External orchestrators can use this API to let Elasticsearch know about the cluster topology, including future changes such as adding or removing nodes. Using this information, the system is able to take better decisions.

It’s possible to run the update in “dry run” mode by adding the ?dry_run query parameter. This will validate the request result, but will not actually perform the update.

Examples

In this example, a new version for the desired nodes with history Ywkh3INLQcuPT49f6kcppA is created. This API only accepts monotonically increasing versions.

  1. resp = client.perform_request(
  2.     "PUT",
  3.     "/_internal/desired_nodes/Ywkh3INLQcuPT49f6kcppA/100",
  4.     headers={"Content-Type": "application/json"},
  5.     body={
  6.         "nodes": [
  7.             {
  8.                 "settings": {
  9.                     "node.name": "instance-000187",
  10.                     "node.external_id": "instance-000187",
  11.                     "node.roles": [
  12.                         "data_hot",
  13.                         "master"
  14.                     ],
  15.                     "node.attr.data": "hot",
  16.                     "node.attr.logical_availability_zone": "zone-0"
  17.                 },
  18.                 "processors": 8,
  19.                 "memory": "58gb",
  20.                 "storage": "2tb"
  21.             }
  22.         ]
  23.     },
  24. )
  25. print(resp)
  1. const response = await client.transport.request({
  2.   method: "PUT",
  3.   path: "/_internal/desired_nodes/Ywkh3INLQcuPT49f6kcppA/100",
  4.   body: {
  5.     nodes: [
  6.       {
  7.         settings: {
  8.           "node.name": "instance-000187",
  9.           "node.external_id": "instance-000187",
  10.           "node.roles": ["data_hot", "master"],
  11.           "node.attr.data": "hot",
  12.           "node.attr.logical_availability_zone": "zone-0",
  13.         },
  14.         processors: 8,
  15.         memory: "58gb",
  16.         storage: "2tb",
  17.       },
  18.     ],
  19.   },
  20. });
  21. console.log(response);
  1. PUT /_internal/desired_nodes/Ywkh3INLQcuPT49f6kcppA/100
  2. {
  3.     "nodes" : [
  4.         {
  5.             "settings" : {
  6.                  "node.name" : "instance-000187",
  7.                  "node.external_id": "instance-000187",
  8.                  "node.roles" : ["data_hot", "master"],
  9.                  "node.attr.data" : "hot",
  10.                  "node.attr.logical_availability_zone" : "zone-0"
  11.             },
  12.             "processors" : 8.0,
  13.             "memory" : "58gb",
  14.             "storage" : "2tb"
  15.         }
  16.     ]
  17. }

The API returns the following result:

  1. {
  2.   "replaced_existing_history_id": false,
  3.   "dry_run": false
  4. }

Additionally, it is possible to specify a processors range. This is helpful in environments where Elasticsearch nodes can be deployed in hosts where the number of processors that the Elasticsearch process can use is guaranteed to be at least the lower range and up to the upper range. This is a common scenario in Linux deployments where cgroups is used.

  1. resp = client.perform_request(
  2.     "PUT",
  3.     "/_internal/desired_nodes/Ywkh3INLQcuPT49f6kcppA/101",
  4.     headers={"Content-Type": "application/json"},
  5.     body={
  6.         "nodes": [
  7.             {
  8.                 "settings": {
  9.                     "node.name": "instance-000187",
  10.                     "node.external_id": "instance-000187",
  11.                     "node.roles": [
  12.                         "data_hot",
  13.                         "master"
  14.                     ],
  15.                     "node.attr.data": "hot",
  16.                     "node.attr.logical_availability_zone": "zone-0"
  17.                 },
  18.                 "processors_range": {
  19.                     "min": 8,
  20.                     "max": 10
  21.                 },
  22.                 "memory": "58gb",
  23.                 "storage": "2tb"
  24.             }
  25.         ]
  26.     },
  27. )
  28. print(resp)
  1. const response = await client.transport.request({
  2.   method: "PUT",
  3.   path: "/_internal/desired_nodes/Ywkh3INLQcuPT49f6kcppA/101",
  4.   body: {
  5.     nodes: [
  6.       {
  7.         settings: {
  8.           "node.name": "instance-000187",
  9.           "node.external_id": "instance-000187",
  10.           "node.roles": ["data_hot", "master"],
  11.           "node.attr.data": "hot",
  12.           "node.attr.logical_availability_zone": "zone-0",
  13.         },
  14.         processors_range: {
  15.           min: 8,
  16.           max: 10,
  17.         },
  18.         memory: "58gb",
  19.         storage: "2tb",
  20.       },
  21.     ],
  22.   },
  23. });
  24. console.log(response);
  1. PUT /_internal/desired_nodes/Ywkh3INLQcuPT49f6kcppA/101
  2. {
  3.     "nodes" : [
  4.         {
  5.             "settings" : {
  6.                  "node.name" : "instance-000187",
  7.                  "node.external_id": "instance-000187",
  8.                  "node.roles" : ["data_hot", "master"],
  9.                  "node.attr.data" : "hot",
  10.                  "node.attr.logical_availability_zone" : "zone-0"
  11.             },
  12.             "processors_range" : {"min": 8.0, "max": 10.0},
  13.             "memory" : "58gb",
  14.             "storage" : "2tb"
  15.         }
  16.     ]
  17. }