Platform - Allocators | Elastic Cloud Enterprise Reference [2.2]

» » »

« Platform Platform - Configuration - Instances - CRUD »

Platform - Allocators

Get allocators

Retrieves the information for all of the allocators in the platform.

Request

GET /api/v1/platform/infrastructure/allocators

Query parameters

Name	Type	Required	Description
`q`	`string`	N	(Optional) The query that filters the allocators. Maps to an Elasticsearch `query_string` query.

Responses

200: (AllocatorOverview) The allocator information is retrieved.

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XGET {{hostname}}/api/v1/platform/infrastructure/allocators \
-u $CLOUD_USER:$CLOUD_KEY

Search allocators

Retrieves the information for all of the allocators in the platform that match the specified query.

Request

POST /api/v1/platform/infrastructure/allocators/_search

Request body

(SearchRequest) The optional search request to execute. If not supplied then all allocators are matched

Responses

200: (AllocatorOverview) The search request succeeded.
400: (BasicFailedReply) The search request failed.

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XPOST {{hostname}}/api/v1/platform/infrastructure/allocators/_search \
-u $CLOUD_USER:$CLOUD_KEY \
-H 'Content-Type: application/json' \
-d '
{
   "from" : 0,
   "query" : {
      "bool" : {
         "filter" : [
            null
         ],
         "minimum_should_match" : 0,
         "must" : [
            null
         ],
         "must_not" : [
            null
         ],
         "should" : [
            null
         ]
      },
      "exists" : {
         "field" : "string"
      },
      "match" : {
         "some_property" : {
            "analyzer" : "string",
            "minimum_should_match" : 0,
            "operator" : "string",
            "query" : "string"
         }
      },
      "match_all" : {},
      "match_none" : {},
      "nested" : {
         "path" : "string",
         "query" : null,
         "score_mode" : "string"
      },
      "prefix" : {
         "some_property" : {
            "boost" : 0.1,
            "value" : "string"
         }
      },
      "query_string" : {
         "allow_leading_wildcard" : true,
         "analyzer" : "string",
         "default_field" : "string",
         "default_operator" : "string",
         "query" : "string"
      },
      "range" : {
         "some_property" : {
            "boost" : 0.1,
            "format" : "string",
            "gt" : {},
            "gte" : {},
            "lt" : {},
            "lte" : {},
            "time_zone" : "string"
         }
      },
      "term" : {
         "some_property" : {
            "value" : {}
         }
      }
   },
   "size" : 0,
   "sort" : [
      "string"
   ]
}
'

Delete allocator

Deletes the allocator.

Request

DELETE /api/v1/platform/infrastructure/allocators/{allocator_id}

Path parameters

Name	Type	Required	Description
`allocator_id`	`string`	Y	The allocator identifier.

Query parameters

Name	Type	Required	Description
`remove_instances`	`boolean`	N	Removes the instances from the deleted allocator.

Responses

200: (EmptyResponse) The allocator is deleted.
400: (BasicFailedReply) The {allocator_id} can't be deleted.
404: (BasicFailedReply) The {allocator_id} can't be found. (code: 'allocators.allocator_not_found')
449: (BasicFailedReply) Elevated permissions are required. (code: '"root.needs_elevated_permissions"')

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XDELETE {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id} \
-u $CLOUD_USER:$CLOUD_KEY

Get allocator

Retrieves the allocator by the ID.

Request

GET /api/v1/platform/infrastructure/allocators/{allocator_id}

Path parameters

Name	Type	Required	Description
`allocator_id`	`string`	Y	The allocator identifier.

Responses

200: (AllocatorInfo) The allocator information is retrieved.
404: (BasicFailedReply) The {allocator_id} can't be found. (code: 'allocators.allocator_not_found')

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XGET {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id} \
-u $CLOUD_USER:$CLOUD_KEY

Resynchronize allocator

Immediately synchronizes the allocator information in the back-end search index and caches.

Request

POST /api/v1/platform/infrastructure/allocators/{allocator_id}/_resync

Path parameters

Name	Type	Required	Description
`allocator_id`	`string`	Y	Allocator identifier

Responses

200: (EmptyResponse) The resynchronization succeeded.
449: (BasicFailedReply) Elevated permissions are required. (code: '"root.needs_elevated_permissions"')
500: (BasicFailedReply) The resynchronization failed. (code: 'allocators.resync_failed')

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XPOST {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id}/_resync \
-u $CLOUD_USER:$CLOUD_KEY

Move clusters

Moves the clusters to a different allocator.

Request

POST /api/v1/platform/infrastructure/allocators/{allocator_id}/clusters/_move

Path parameters

Name	Type	Required	Description
`allocator_id`	`string`	Y	The allocator identifier.

Query parameters

Name	Type	Required	Description
`allocator_down`	`boolean`	N	When `true`, considers all instances on the allocator as permanently shut down when deciding how to migrate data to new nodes.When left blank, the system automatically decides. NOTE: The default treats the allocator as up.
`force_update`	`boolean`; default: `false`	N	When `true`, cancels and overwrites the pending plans, or treats the instance as an error.
`move_only`	`boolean`; default: `true`	N	When `true`, moves the specified instances and ignores the changes for the cluster state.
`validate_only`	`boolean`; default: `false`	N	When `true`, validates the plan overrides, then returns the plan without performing the move.

Request body

(MoveClustersRequest) Overrides defaults for the move of each cluster

Responses

202: (MoveClustersCommandResponse) The move is in progress. To monitor progress, use the GET command on the /{cluster_id} resource.
400: (BasicFailedReply) The Elasticsearch cluster plan contains errors. (code: 'clusters.cluster_invalid_plan' and 'clusters.plan_feature_not_implemented')
403: (BasicFailedReply) The move command is prohibited for the allocator.
449: (BasicFailedReply) Elevated permissions are required. (code: '"root.needs_elevated_permissions"')

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XPOST {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id}/clusters/_move \
-u $CLOUD_USER:$CLOUD_KEY \
-H 'Content-Type: application/json' \
-d '
{
   "apm_clusters" : [
      {
         "cluster_ids" : [
            "string"
         ],
         "plan_override" : {
            "plan_configuration" : {
               "calm_wait_time" : 0,
               "cluster_reboot" : "string",
               "extended_maintenance" : true,
               "move_allocators" : [
                  {
                     "allocator_down" : true,
                     "from" : "string",
                     "to" : [
                        "string"
                     ]
                  }
               ],
               "move_instances" : [
                  {
                     "from" : "string",
                     "instance_down" : true,
                     "to" : [
                        "string"
                     ]
                  }
               ],
               "preferred_allocators" : [
                  "string"
               ],
               "reallocate_instances" : true,
               "timeout" : 0
            },
            "strategy" : {
               "grow_and_shrink" : {},
               "rolling" : {
                  "allow_inline_resize" : true,
                  "group_by" : "string",
                  "shard_init_wait_time" : 0,
                  "skip_synced_flush" : true
               },
               "rolling_grow_and_shrink" : {}
            }
         }
      }
   ],
   "elasticsearch_clusters" : [
      {
         "cluster_ids" : [
            "string"
         ],
         "plan_override" : {
            "cluster_settings_json" : {},
            "plan_configuration" : {
               "calm_wait_time" : 0,
               "cluster_reboot" : "string",
               "extended_maintenance" : true,
               "max_snapshot_age" : 0,
               "max_snapshot_attempts" : 0,
               "move_allocators" : [
                  null
               ],
               "move_instances" : [
                  null
               ],
               "move_only" : true,
               "override_failsafe" : true,
               "preferred_allocators" : [
                  "string"
               ],
               "reallocate_instances" : true,
               "skip_data_migration" : true,
               "skip_post_upgrade_steps" : true,
               "skip_snapshot" : true,
               "skip_upgrade_checker" : true,
               "timeout" : 0
            },
            "restore_snapshot" : {
               "repository_config" : {
                  "raw_settings" : {}
               },
               "repository_name" : "string",
               "restore_payload" : {
                  "indices" : [
                     "string"
                  ],
                  "raw_settings" : {}
               },
               "snapshot_name" : "string",
               "source_cluster_id" : "string",
               "strategy" : "string"
            },
            "strategy" : null
         }
      }
   ],
   "kibana_clusters" : [
      {
         "cluster_ids" : [
            "string"
         ],
         "plan_override" : {
            "plan_configuration" : {
               "calm_wait_time" : 0,
               "cluster_reboot" : "string",
               "extended_maintenance" : true,
               "move_allocators" : [
                  null
               ],
               "move_instances" : [
                  null
               ],
               "preferred_allocators" : [
                  "string"
               ],
               "reallocate_instances" : true,
               "timeout" : 0
            },
            "strategy" : null
         }
      }
   ]
}
'

Move clusters by type

Moves the clusters, by type, to a different allocator.

Request

POST /api/v1/platform/infrastructure/allocators/{allocator_id}/clusters/{cluster_type}/_move

Path parameters

Name	Type	Required	Description
`allocator_id`	`string`	Y	The allocator identifier.
`cluster_type`	`string`; allowed values: [`elasticsearch`, `kibana`]	Y	The cluster types to move off of the allocator. NOTE: When unspecified, all clusters are moved.

Query parameters

Name	Type	Required	Description
`allocator_down`	`boolean`; default: `false`	N	When `true`, considers all instances on the allocator as permanently shut down when deciding how to migrate data to new nodes.When left blank, the system automatically decides. NOTE: The default treats the allocator as up.
`force_update`	`boolean`; default: `false`	N	When true, cancels and overwrites pending plans, or treats instance as an error
`move_only`	`boolean`; default: `true`	N	When true, bypasses the cluster state changes, but continues to move the specified instances
`validate_only`	`boolean`; default: `false`	N	When `true`, validates the plan overrides, then returns the plan without performing the move.

Request body

(MoveClustersRequest) Overrides defaults for the move of each cluster

Responses

202: (MoveClustersCommandResponse) The move is in progress. To monitor progress, use the GET command on the /{cluster_id} resource.
400: (BasicFailedReply) The Elasticsearch cluster plan contains errors. (code: 'clusters.cluster_invalid_plan' and 'clusters.plan_feature_not_implemented')
403: (BasicFailedReply) The move command is prohibited for the allocator.
449: (BasicFailedReply) Elevated permissions are required. (code: '"root.needs_elevated_permissions"')

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XPOST {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id}/clusters/{cluster_type}/_move \
-u $CLOUD_USER:$CLOUD_KEY \
-H 'Content-Type: application/json' \
-d '
{
   "apm_clusters" : [
      {
         "cluster_ids" : [
            "string"
         ],
         "plan_override" : {
            "plan_configuration" : {
               "calm_wait_time" : 0,
               "cluster_reboot" : "string",
               "extended_maintenance" : true,
               "move_allocators" : [
                  {
                     "allocator_down" : true,
                     "from" : "string",
                     "to" : [
                        "string"
                     ]
                  }
               ],
               "move_instances" : [
                  {
                     "from" : "string",
                     "instance_down" : true,
                     "to" : [
                        "string"
                     ]
                  }
               ],
               "preferred_allocators" : [
                  "string"
               ],
               "reallocate_instances" : true,
               "timeout" : 0
            },
            "strategy" : {
               "grow_and_shrink" : {},
               "rolling" : {
                  "allow_inline_resize" : true,
                  "group_by" : "string",
                  "shard_init_wait_time" : 0,
                  "skip_synced_flush" : true
               },
               "rolling_grow_and_shrink" : {}
            }
         }
      }
   ],
   "elasticsearch_clusters" : [
      {
         "cluster_ids" : [
            "string"
         ],
         "plan_override" : {
            "cluster_settings_json" : {},
            "plan_configuration" : {
               "calm_wait_time" : 0,
               "cluster_reboot" : "string",
               "extended_maintenance" : true,
               "max_snapshot_age" : 0,
               "max_snapshot_attempts" : 0,
               "move_allocators" : [
                  null
               ],
               "move_instances" : [
                  null
               ],
               "move_only" : true,
               "override_failsafe" : true,
               "preferred_allocators" : [
                  "string"
               ],
               "reallocate_instances" : true,
               "skip_data_migration" : true,
               "skip_post_upgrade_steps" : true,
               "skip_snapshot" : true,
               "skip_upgrade_checker" : true,
               "timeout" : 0
            },
            "restore_snapshot" : {
               "repository_config" : {
                  "raw_settings" : {}
               },
               "repository_name" : "string",
               "restore_payload" : {
                  "indices" : [
                     "string"
                  ],
                  "raw_settings" : {}
               },
               "snapshot_name" : "string",
               "source_cluster_id" : "string",
               "strategy" : "string"
            },
            "strategy" : null
         }
      }
   ],
   "kibana_clusters" : [
      {
         "cluster_ids" : [
            "string"
         ],
         "plan_override" : {
            "plan_configuration" : {
               "calm_wait_time" : 0,
               "cluster_reboot" : "string",
               "extended_maintenance" : true,
               "move_allocators" : [
                  null
               ],
               "move_instances" : [
                  null
               ],
               "preferred_allocators" : [
                  "string"
               ],
               "reallocate_instances" : true,
               "timeout" : 0
            },
            "strategy" : null
         }
      }
   ]
}
'

Start maintenance mode

Starts maintenance mode on the allocator.

Request

POST /api/v1/platform/infrastructure/allocators/{allocator_id}/maintenance-mode/_start

Path parameters

Name	Type	Required	Description
`allocator_id`	`string`	Y	Allocator identifier

Responses

202: (EmptyResponse) The start maintenance mode command was issued successfully
403: (BasicFailedReply) The start maintenance mode command was prohibited for the given cluster.
404: (BasicFailedReply) The allocator specified by {allocator_id} cannot be found (code: 'allocators.allocator_not_found')
449: (BasicFailedReply) elevated permissions are required. (code: '"root.unauthorized.rbac.elevated_permissions_required"')

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XPOST {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id}/maintenance-mode/_start \
-u $CLOUD_USER:$CLOUD_KEY

Stop maintenance mode

Stops maintenance mode on the allocator.

Request

POST /api/v1/platform/infrastructure/allocators/{allocator_id}/maintenance-mode/_stop

Path parameters

Name	Type	Required	Description
`allocator_id`	`string`	Y	Allocator identifier

Responses

202: (EmptyResponse) The stop maintenance mode command was issued successfully
403: (BasicFailedReply) The stop maintenance mode command was prohibited for the given cluster.
404: (BasicFailedReply) The allocator specified by {allocator_id} cannot be found (code: 'allocators.allocator_not_found')
449: (BasicFailedReply) elevated permissions are required. (code: '"root.unauthorized.rbac.elevated_permissions_required"')

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XPOST {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id}/maintenance-mode/_stop \
-u $CLOUD_USER:$CLOUD_KEY

Get allocator metadata

Retrieves the allocator metadata.

Request

GET /api/v1/platform/infrastructure/allocators/{allocator_id}/metadata

Path parameters

Name	Type	Required	Description
`allocator_id`	`string`	Y	The allocator identifier.

Responses

200

(array[MetadataItem]) The allocator metadata is returned.

Headers

x-cloud-resource-created (string): The date-time when the resource was created (ISO format relative to UTC)
x-cloud-resource-last-modified (string): The date-time when the resource was last modified (ISO format relative to UTC)
x-cloud-resource-version (string): The resource version, which is used to avoid update conflicts with concurrent operations

404

(BasicFailedReply) The {allocator_id} can't be found. (code: 'allocators.allocator_not_found')

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XGET {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id}/metadata \
-u $CLOUD_USER:$CLOUD_KEY

Set allocator metadata

Sets the allocator metadata.

Request

PUT /api/v1/platform/infrastructure/allocators/{allocator_id}/metadata

Path parameters

Name	Type	Required	Description
`allocator_id`	`string`	Y	The allocator identifier.

Query parameters

Name	Type	Required	Description
`version`	`integer`	N	Checks for conflicts against the metadata version, then returns the value in the `x-cloud-resource-version` header.

Request body

(MetadataItems) (required) The metadata to update the allocator with

Responses

200: (array[MetadataItem]) The allocator metadata successfully changed.
400: (BasicFailedReply) The metadata tag is missing. Specify the metadata tag value, then try again. (code: 'allocators.invalid_empty_metadata_items')
404: (BasicFailedReply) The {allocator_id} can't be found. (code: 'allocators.allocator_not_found')
449: (BasicFailedReply) Elevated permissions are required. (code: '"root.needs_elevated_permissions"')

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XPUT {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id}/metadata \
-u $CLOUD_USER:$CLOUD_KEY \
-H 'Content-Type: application/json' \
-d '
{
   "items" : [
      {
         "key" : "string",
         "value" : "string"
      }
   ]
}
'

Delete allocator metadata item

Removes a single item from the allocator metadata.

Request

DELETE /api/v1/platform/infrastructure/allocators/{allocator_id}/metadata/{key}

Path parameters

Name	Type	Required	Description
`allocator_id`	`string`	Y	The allocator identifier.
`key`	`string`	Y	The metadata item key to remove.

Query parameters

Name	Type	Required	Description
`version`	`integer`	N	Checks for conflicts against the metadata version, then returns the value in the `x-cloud-resource-version` header.

Responses

200: (array[MetadataItem]) The allocator metadata item is deleted.
404: (BasicFailedReply) The {allocator_id} can't be found. (code: 'allocators.allocator_not_found')
449: (BasicFailedReply) Elevated permissions are required. (code: '"root.needs_elevated_permissions"')

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XDELETE {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id}/metadata/{key} \
-u $CLOUD_USER:$CLOUD_KEY

Set allocator metadata item

Adds or updates a single item in the allocator metadata.

Request

PUT /api/v1/platform/infrastructure/allocators/{allocator_id}/metadata/{key}

Path parameters

Name	Type	Required	Description
`allocator_id`	`string`	Y	The allocator identifier.
`key`	`string`	Y	The metadata item key.

Query parameters

Name	Type	Required	Description
`version`	`integer`	N	Checks for conflicts against the metadata version, then returns the value in the `x-cloud-resource-version` header.

Request body

(MetadataItemValue) (required) The value of the metadata item to add or update

Responses

200: (array[MetadataItem]) The allocator metadata was successfully changed (the updated JSON is returned)
400: (BasicFailedReply) The value specified for the metadata tag is empty (code: 'allocators.invalid_empty_metadata_item')
404: (BasicFailedReply) The allocator specified by {allocator_id} cannot be found (code: 'allocators.allocator_not_found') or the metadata item specified by {key} cannot be found (code: 'allocators.metadata_item_not_found')
449: (BasicFailedReply) elevated permissions are required. (code: '"root.unauthorized.rbac.elevated_permissions_required"')

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XPUT {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id}/metadata/{key} \
-u $CLOUD_USER:$CLOUD_KEY \
-H 'Content-Type: application/json' \
-d '
{
   "value" : "string"
}
'

Get allocator settings

Retrieves the allocator override settings.

Request

GET /api/v1/platform/infrastructure/allocators/{allocator_id}/settings

Path parameters

Name	Type	Required	Description
`allocator_id`	`string`	Y	The allocator identifier.

Responses

200

(AllocatorSettings) The allocator settings are retrieved.

Headers

x-cloud-resource-created (string): The date-time when the resource was created (ISO format relative to UTC)
x-cloud-resource-last-modified (string): The date-time when the resource was last modified (ISO format relative to UTC)
x-cloud-resource-version (string): The resource version, which is used to avoid update conflicts with concurrent operations

404

(BasicFailedReply) The {allocator_id} can't be found. (code: 'allocators.allocator_not_found')

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XGET {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id}/settings \
-u $CLOUD_USER:$CLOUD_KEY

Update allocator settings

Applies the settings as a patch. Only the fields that are referenced in the update are altered.

Request

PATCH /api/v1/platform/infrastructure/allocators/{allocator_id}/settings

Path parameters

Name	Type	Required	Description
`allocator_id`	`string`	Y	The allocator identifier.

Query parameters

Name	Type	Required	Description
`version`	`integer`	N	Checks for conflicts against the metadata version, then returns the value in the `x-cloud-resource-version` header.

Request body

(AllocatorSettings) (required) The allocator settings to update

Responses

200: (AllocatorSettings) The allocator settings successfully updated.
404: (BasicFailedReply) The {allocator_id} can't be found. (code: 'allocators.allocator_not_found')
449: (BasicFailedReply) Elevated permissions are required. (code: '"root.needs_elevated_permissions"')

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XPATCH {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id}/settings \
-u $CLOUD_USER:$CLOUD_KEY \
-H 'Content-Type: application/json' \
-d '
{
   "capacity" : 0
}
'

Set allocator settings

Overwrites the allocator settings with the specified settings. WARNING: Any unspecified fields are deleted.

Request

PUT /api/v1/platform/infrastructure/allocators/{allocator_id}/settings

Path parameters

Name	Type	Required	Description
`allocator_id`	`string`	Y	The allocator identifier.

Query parameters

Name	Type	Required	Description
`version`	`integer`	N	Checks for conflicts against the metadata version, then returns the value in the `x-cloud-resource-version` header.

Request body

(AllocatorSettings) (required) The allocator settings to apply

Responses

200: (AllocatorSettings) The allocator settings successfully changed.
404: (BasicFailedReply) The {allocator_id} can't be found. (code: 'allocators.allocator_not_found')
449: (BasicFailedReply) Elevated permissions are required. (code: '"root.needs_elevated_permissions"')

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XPUT {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id}/settings \
-u $CLOUD_USER:$CLOUD_KEY \
-H 'Content-Type: application/json' \
-d '
{
   "capacity" : 0
}
'

« Platform Platform - Configuration - Instances - CRUD »