Set upgrade mode API

POST _ml/set_upgrade_mode

Requires the manage_ml cluster privilege. This privilege is included in the machine_learning_admin built-in role.

When upgrading your cluster, in some circumstances you must restart your nodes and reindex your machine learning indices. In those circumstances, there must be no machine learning jobs running. You can close the machine learning jobs, do the upgrade, then open all the jobs again. Alternatively, you can use this API to temporarily halt tasks associated with the jobs and datafeeds and prevent new jobs from opening. You can also use this API during upgrades that do not require you to reindex your machine learning indices, though stopping jobs is not a requirement in that case.

For more information, see Upgrading the Elastic Stack.

When enabled=true this API temporarily halts all job and datafeed tasks and prohibits new job and datafeed tasks from starting.

Subsequently, you can call the API with the enabled parameter set to false, which causes machine learning jobs and datafeeds to return to their desired states.

You can see the current value for the upgrade_mode setting by using the get machine learning info API.

The following example enables upgrade_mode for the cluster:

resp = client.ml.set_upgrade_mode(
    enabled=True,
    timeout="10m",
)
print(resp)

response = client.ml.set_upgrade_mode(
  enabled: true,
  timeout: '10m'
)
puts response

const response = await client.ml.setUpgradeMode({
  enabled: "true",
  timeout: "10m",
});
console.log(response);

POST _ml/set_upgrade_mode?enabled=true&timeout=10m

When the call is successful, an acknowledged response is returned. For example:

{
  "acknowledged": true
}

The acknowledged response will only be returned once all machine learning jobs and datafeeds have finished writing to the machine learning internal indices. This means it is safe to reindex those internal indices without causing failures. You must wait for the acknowledged response before reindexing to ensure that all writes are completed.

When the upgrade is complete, you must set upgrade_mode to false for machine learning jobs to start running again. For example:

resp = client.ml.set_upgrade_mode(
    enabled=False,
    timeout="10m",
)
print(resp)

response = client.ml.set_upgrade_mode(
  enabled: false,
  timeout: '10m'
)
puts response

const response = await client.ml.setUpgradeMode({
  enabled: "false",
  timeout: "10m",
});
console.log(response);

POST _ml/set_upgrade_mode?enabled=false&timeout=10m